/*
 * 2002 - 2022 BroadSign International, LLC
 */

syntax = "proto3";

import "google/api/annotations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

package Broadsign.Services.Playlist;
option cc_enable_arenas = true;

/*
 * The hash of the data for one content.
 */
message ContentHash {
	enum HashType {
		NONE = 0;
		CRC32 = 1;
	}

	HashType type = 1;      // Which hashing algorithm was used to generate the payload.
	bytes payload = 2;      // Payload data. The contents are dependant on the algorithm used.
}

message Frame {
	uint64 frame_id = 1;                    // Broadsign frame identifier.
	repeated uint32 filler_indices = 2;
	string name = 3;
	repeated uint32 criteria_indices = 4;   // List of criterias associated to this frame
}

message Campaign {
	uint64 campaign_id = 1;             // Broadsign campaign identifier.
	map<string, string> variables = 2;  // Custom variables to customize playback. Values can override Content variables.
										// Values can be overridden by Identification variables.
}

message Geometry {
	int32 x = 1;
	int32 y = 2;
	int32 z = 3;
	int32 width = 4;
	int32 height = 5;
	bool fullscreen = 6;
}

message DataSynchronization {
	enum Behavior {
		INVALID = 0;
		FILE_SYNCHRONIZATION = 1;
	};

	string from = 1;
	string to = 2;
	Behavior behavior = 3;
	google.protobuf.Duration expiry = 4;
	google.protobuf.Duration refresh_period = 5;
	google.protobuf.Duration timeout_period = 6;
}

/*
 * A media element to be displayed.
 */
message Content {
	string name = 1;
	string mime_type = 2;									// The file format defined by the file extension. Example: 'png'.
	string uri = 3;											// The URL to the content. Example: 'https://p.com/path/123.png'.
	uint64 size = 4;										// The file size in bytes.
	ContentHash hash = 5;									// The hash of this content.

	google.protobuf.Int32Value percent_volume_override = 6;	// Volume should be set to this value during playback of this content. If defined, varies between 0 and 200.

	map<string, string> variables = 7;						// Custom variables associated to the content. Values can be overridden by Campaign and Identification variables.
	uint64 ad_copy_id = 8;									// The ad copy from which this content was derived.
	oneof content_type_specific_parameters {				// Parameters for specific content types.
		google.protobuf.Empty no_parameters = 9;
		HtmlPackageParameters html_package_parameters = 10;
	}

	repeated DataSynchronization data_synchronizations = 11;
}

message HtmlPackageParameters {
	string main_html_file_path = 1;
}

/*
 * An item in a playlist.
 */
message PlaylistItem {
	google.protobuf.Timestamp start_time = 1; // When this item is expected to start playing
	google.protobuf.Duration duration = 2;    // The duration of this item.
	bytes token = 3;                          // A token to confirm playback.

	uint32 content_index = 4;                 // The content to play to fulfill this item. The index is
											  // a 0-based position within the Playlist contents list.
	uint32 campaign_index = 5;                // The campaign from which this item was generated. The index is
											  // a 0-based position within the Playlist campaigns list.
	uint32 frame_index = 6;                   // The frame on which this item was scheduled to play. The index is
											  // a 0-based position within the Playlist frames list.
	uint32 geometry_index = 7;				  // The geometry at which the content should be played. The index is
											  // a 0-based position within the Playlist geometries list.
}

/*
 * Identification information for the Broadsign player for which the playlist is generated.
 */
message Identification {
	message Geolocation {
		double latitude = 1;
		double longitude = 2;
	}

	uint64 player_id = 1;                     // Broadsign player identifier
	uint64 display_unit_id = 2;               // Display unit identifier.
	Geolocation display_unit_latlong = 3;     // Geolocation associated to the display unit.
	string display_unit_address = 4;          // Address associated to the display unit.
	string display_unit_location_code = 5;    // Location code or zip associated to display unit.

	map<string, string> variables = 6;        // Player or display unit custom variables.
}

/*
 * Use conditions to control when and where content should and should not play.
 */
message Condition {
	string name = 1;
	bool exclusive = 2;
}

/*
 * Errors that can occur during playlist
 *
 * These errors can explain gaps in the playlist
 */
 enum Error {
	NO_ERROR = 0;
	CAMPAIGN_NOT_SCHEDULED_ON_FRAME = 1;	// (Synchronization) Follower tried to adapt leader's
											// playlist, but encountered an item whose campaign
											// was not scheduled for its current active frame.
											// The item was skipped.
};

/*
 * A list of content-duration pairings that were configured as filler in BCA.
 * These can be used in case the client runs out of playlist items and cannot
 * contact the Air server for more.
 */
message Filler {
	uint32 content_index = 1;
	google.protobuf.Duration duration = 2;
}

message Playlist {
	repeated PlaylistItem items = 1;
}

message Criteria {
	uint64 criteria_id = 1;
	string name = 2;
}

/*
 * A content list request.
 *
 * Parameter for the 'GenerateContentList' API call.
 */
message GenerateContentListRequest {
	string player_identifier = 1;           // Custom unique identifier assigned to your Broadsign
											// player, expected to represent a unique venue.
	string screen_identifier = 2;           // Identifier for one screen within a venue.

	/*
	 * Desired time duration covered by the generated Playlist.
	 *
	 * For example, if duration is 1 hour, the returned Playlist will cover the next hour. The
	 * total duration of the returned items may be shorter than the covered time, for example
	 * if there are times where nothing is scheduled to play.
	 *
	 * To improve caching effectiveness and response performance, two values are currently
	 * supported:
	 * - 1 hour (default if omitted).
	 * - 48 hours.
	 *
	 * The API may reject requests with different duration values. We may relax this requirement
	 * in future releases.
	 */
	google.protobuf.Duration duration = 3;
	bool exclude_programmatic_precaching_info = 4;	// (optional) By setting this to true, external
													// content will not be returned along with the
													// internal Broadsign. EX: Reach
}

/*
 * A content list result.
 *
 * Return value for the 'GenerateContentList' API call.
 */
message GenerateContentListResponse  {
	reserved 1;

	repeated Content contents = 2;
	repeated Filler fillers = 3;
	repeated DataSynchronization data_synchronizations = 4;
}

/*
 * A playlist generation request.
 *
 * Parameter for the 'GeneratePlaylist' API call.
 */
message GeneratePlaylistRequest {
	string player_identifier = 1;			// Custom unique identifier assigned to your Broadsign
											// player, expected to represent a unique venue.
	string screen_identifier = 2;			// Identifier for one screen within a venue.

	/*
	 * Desired time duration covered by the generated Playlist.
	 *
	 * For example, if duration is 1 hour, the returned Playlist will cover the next hour. The
	 * total duration of the returned items may be shorter than the covered time, for example
	 * if there are times where nothing is scheduled to play.
	 *
	 * To improve caching effectiveness and response performance, two values are currently
	 * supported:
	 * - 1 hour (default if omitted).
	 * - 48 hours.
	 *
	 * The API may reject requests with different duration values. We may relax this requirement
	 * in future releases.
	 */
	google.protobuf.Duration duration = 3;

	/*
	*	List of active conditions
	*/
	repeated Condition active_conditions = 4;			// Condition(s) on the playlist request.

	google.protobuf.Timestamp next_expected_poll = 5;	// (optional) The next time GeneratePlaylist
														// is expected to be called. This value will
														// be used to determine if the player is
														// healthy or not.

	bool exclude_programmatic_precaching_info = 6;			// (optional) By setting this to true, the content
															// section will only contain the content in the
															// returned playlist and will not contain any
															// additional content EX: Reach

	bool force = 7; // (optional) Setting this option to true will:
					//  - immediately poll, no matter when the last poll was.
					//  - drop the cached playlist and force regeneration.
}

/*
 * A generated playlist result (contains a single playlist).
 *
 * Return value for the 'GeneratePlaylist' API call.
 */
message GeneratePlaylistResponse {
	repeated PlaylistItem items = 1;						// An ordered sequence of playlist items.
	repeated Content contents = 2;							// Content files referred to by playlist items.
	Identification identification = 3;						// Identification information for the Broadsign player for
															// which the playlist is generated.
	repeated Campaign campaigns = 4;						// Campaigns referred to by playlist items.
	repeated Frame frames = 5;								// Frames referred to by playlist items.
	repeated Geometry geometries = 6;						// Geometries referred to by playlist items.
	repeated Error errors = 7;								// Errors that occured during generation.
	repeated Filler fillers = 8;							// Offline filler
	repeated DataSynchronization data_synchronizations = 9;	// Data Synchronization from player configuration
	repeated Criteria criterias = 10;
}

/*
 * A playback confirmation request.
 *
 * Parameter for the 'ConfirmPlayback' API call.
 */
message ConfirmPlaybackRequest {
	string player_identifier = 1;           // Unique Broadsign Player identifier, expected to
											// represent a unique venue.
	string screen_identifier = 2;           // Identifier for one screen within a venue.

	message ConfirmedItem {
		bytes playlist_item_token = 1;
		map<string, string> custom_data = 2;
		bool screen_not_ok = 3;
	}
	repeated ConfirmedItem confirmed_items = 3;
}

/*
 * A playback confirmation result (contains no data).
 *
 * Return value for the 'ConfirmPlayback' API call. No data is currently returned other than the
 * success/failure of the call.
 */
message ConfirmPlaybackResponse {
	repeated bytes missed_timebox_items = 1;	// Submitted tokens that were rejected because
												// their timeboxes had expired.
}

/*
 * PlaylistService interface and HTTP+JSON API mapping.
 */
service PlaylistService {
	rpc GeneratePlaylist(GeneratePlaylistRequest) returns (GeneratePlaylistResponse) {
		option (google.api.http) = { post: "/playlist/v1/generate" };
	}

	rpc ConfirmPlayback(ConfirmPlaybackRequest) returns (ConfirmPlaybackResponse) {
		option (google.api.http) = { post: "/playlist/v1/confirm_playback" };
	}

	rpc GenerateContentList(GenerateContentListRequest) returns (GenerateContentListResponse ) {
		option (google.api.http) = { post: "/playlist/v1/content" };
	}
}