Приложения-отправители Google Cast управляют воспроизведением на устройстве-приемнике, отправляя сообщения в формате JSON в приложение-приемник. Аналогичным образом, приемник отправляет сообщения обратно отправителю, также в формате JSON. Сообщения могут представлять собой команды от отправителя, изменяющие состояние проигрывателя, ответы на эти команды от приемника или структуры данных, описывающие медиафайлы для приложения-приемника.
В соответствии с дополнительными условиями использования Google Cast SDK , медиаприложение Cast должно использовать эти сообщения, определенные здесь, для управления воспроизведением мультимедиа на приемнике. Это обеспечивает единообразный пользовательский опыт на разных платформах и гарантирует поддержку новых и будущих сценариев использования приложением Cast. Эти структуры также поддерживают пользовательские данные, где это уместно, и приложение может определять свои собственные сообщения для команд, не поддерживаемых SDK.
Пространство имен для сообщений воспроизведения мультимедиа определено как urn:x-cast:com.google.cast.media .
Примечание: Сообщения и структуры, описанные в данной спецификации, имеют неявный максимальный размер, определяемый максимальным размером транспортного сообщения; для отдельных полей ограничений нет. Максимальный размер транспортного сообщения в настоящее время составляет 64 Кбайта.
Общие структуры данных пространства имен
В общем пространстве имен определен расширенный набор структур данных, используемых всеми артефактами пространства имен медиафайлов.
Изображение
Это описание изображения, включающее небольшой объем метаданных, позволяющий приложению-отправителю выбирать изображения в зависимости от способа их отображения.
Высота и ширина являются необязательными только для одного элемента в массиве изображений. Например, если возвращается один элемент, то они необязательны; если возвращаются два элемента, один из них должен указывать высоту и ширину, но отправитель может выбрать вариант «по умолчанию», если его не устраивает вариант, переданный с конкретными параметрами.
| Имя | Тип | Описание |
|---|---|---|
| url | URI | URI для изображения |
| высота | целое число | необязательная высота изображения |
| ширина | целое число | необязательная ширина изображения |
Объем
Громкость медиапотока. Используется для эффектов плавного нарастания/затухания медиапотока. (Примечание: системная громкость изменяется с помощью API отправителя.) Громкость потока не должна использоваться совместно с ползунком громкости или кнопками регулировки громкости для управления громкостью устройства. Для изменения громкости потока необходимо передать хотя бы один из следующих параметров.
| Имя | Тип | Описание |
|---|---|---|
| уровень | двойной | Необязательный параметр: текущий уровень громкости потока в диапазоне от 0,0 до 1,0, где 1,0 — максимальная громкость. |
| приглушенный | логический | (Необязательно) Определяет, отключен ли звук устройства Cast, независимо от уровня громкости. |
Структуры данных пространства имен медиафайлов
Эти сообщения описывают состояние медиаплеера. Пространство имен : urn:x-cast:com.google.cast.media .
МедиаИнформация
Эта структура данных описывает медиапоток.
| Имя | Тип | Описание |
|---|---|---|
| contentId | нить | Идентификатор контента, загружаемого в данный момент медиаплеером, специфичный для конкретного приложения. Это строка произвольной формы, специфичная для данного приложения. В большинстве случаев это будет URL-адрес медиафайла, но отправитель может передать строку, которую получатель сможет правильно интерпретировать. Максимальная длина: 1 КБ. |
| streamType | перечисление (нить) | Описывает тип медиаартефакта как один из следующих:
|
| contentType | нить | MIME-тип контента воспроизводимого медиафайла |
| метаданные | объект | Необязательный объект метаданных медиафайлов, один из следующих: |
| продолжительность | двойной | (необязательно) Длительность воспроизводимого в секундах потока |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый либо приложением-отправителем, либо приложением-получателем. |
GenericMediaMetadata
Описывает типичный медиа-артефакт.
| Имя | Тип | Описание |
|---|---|---|
| метаданныеТип | целое число | 0 (единственное значение) |
| заголовок | нить | Необязательное описательное название контента. Игрок может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| субтитры | нить | Дополнительный описательный подзаголовок контента. Плеер может получить заголовок самостоятельно, используя content_id, или же он может быть указан отправителем в сообщении Load. |
| изображения | Изображение [] | Необязательный массив URL-адресов изображений, связанных с контентом. Начальное значение поля может быть указано отправителем в сообщении загрузки . Должен содержать рекомендуемые размеры. |
| Дата выпуска | строка (ISO 8601) | Необязательная дата и время выпуска контента в формате ISO 8601. Плеер может самостоятельно получить название, используя content_id, или же этот идентификатор может быть указан отправителем в сообщении Load. |
MovieMediaMetadata
Описывает медиаартефакт, связанный с фильмом.
| Имя | Тип | Описание |
|---|---|---|
| метаданныеТип | целое число | 1 (единственное значение) |
| заголовок | нить | Необязательное описательное название контента. Игрок может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| субтитры | нить | Дополнительный описательный подзаголовок контента. Плеер может получить заголовок самостоятельно, используя content_id, или же он может быть указан отправителем в сообщении Load. |
| студия | нить | Необязательный идентификатор студии, выпустившей контент. Игрок может самостоятельно получить информацию о студии, используя content_id, или же она может быть указана отправителем в сообщении Load. |
| изображения | Изображение [] | Необязательный массив URL-адресов изображений, связанных с контентом. Начальное значение поля может быть указано отправителем в сообщении загрузки . Должен содержать рекомендуемые размеры. |
| Дата выпуска | строка (ISO 8601) | Необязательная дата и время выпуска контента в формате ISO 8601. Плеер может самостоятельно получить название, используя content_id, или же этот идентификатор может быть указан отправителем в сообщении Load. |
TvShowMediaMetadata
Описывает медиа-артефакт эпизода телешоу.
| Имя | Тип | Описание |
|---|---|---|
| метаданныеТип | целое число | 2 (единственное значение) |
| название серии | нить | Необязательно. Описательное название сериала. Плеер может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| субтитры | нить | Дополнительные описательные субтитры к эпизоду телесериала. Плеер может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load . |
| сезон | целое число | необязательный номер сезона телешоу |
| эпизод | целое число | (необязательно) Номер эпизода (в сезоне) телешоу |
| изображения | Изображение [] | Необязательный массив URL-адресов изображений, связанных с контентом. Начальное значение поля может быть указано отправителем в сообщении загрузки . Должен содержать рекомендуемые размеры. |
| оригинальная дата выхода в эфир | строка (ISO 8601) | Необязательная дата и время выхода эпизода в формате ISO 8601. Плеер может самостоятельно получить originalAirDate, используя content_id, или же эта информация может быть предоставлена отправителем в сообщении Load. |
MusicTrackMediaMetadata
Описывает медиа-артефакт музыкального трека.
| Имя | Тип | Описание |
|---|---|---|
| метаданныеТип | целое число | 3 (единственное значение) |
| название альбома | нить | Необязательный альбом или коллекция, из которой взят этот трек. Плеер может получить название альбома самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| заголовок | нить | Необязательное название трека (например, название песни). Плеер может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| альбомИсполнитель | нить | Необязательное имя исполнителя, связанное с альбомом, содержащим этот трек. Плеер может самостоятельно получить имя исполнителя альбома, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| художник | нить | Необязательное имя исполнителя, связанное с медиатреком. Плеер может самостоятельно получить имя исполнителя, используя content_id, или же оно может быть указано отправителем в сообщении Load . |
| композитор | нить | Необязательное имя композитора, связанного с медиатреком. Плеер может получить имя композитора самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load . |
| номер трека | целое число | (необязательно) Номер трека на альбоме |
| номер диска | целое число | Необязательный номер тома (например, диска) альбома. |
| изображения | Изображение [] | Необязательный массив URL-адресов изображений, связанных с контентом. Начальное значение поля может быть указано отправителем в сообщении загрузки . Должен содержать рекомендуемые размеры. |
| Дата выпуска | строка (ISO 8601) | Необязательная дата и время выпуска контента в формате ISO 8601. Плеер может получить дату выпуска самостоятельно, используя content_id, или же она может быть указана отправителем в сообщении Load. |
PhotoMediaMetadata
Описывает артефакт, связанный с фотографическими носителями информации.
| Имя | Тип | Описание |
|---|---|---|
| метаданныеТип | целое число | 4 (единственное значение) |
| заголовок | нить | Необязательное название фотографии. Плеер может получить название самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| художник | нить | Необязательное имя фотографа. Плеер может самостоятельно получить имя фотографа, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
| расположение | нить | Необязательное поле для указания местоположения, где была сделана фотография; например, «Мадрид, Испания». Игрок может самостоятельно получить местоположение, используя content_id, или же оно может быть указано отправителем в сообщении Load . |
| широта | двойной | Необязательное значение географической широты для места, где была сделана фотография. Игрок может получить широту самостоятельно, используя content_id, или же она может быть указана отправителем в сообщении Load. |
| долгота | двойной | Необязательное значение географической долготы для места, где была сделана фотография. Игрок может самостоятельно получить долготу, используя content_id, или она может быть указана отправителем в сообщении Load . |
| ширина | целое число | Необязательная ширина фотографии в пикселях. Плеер может получить ширину самостоятельно, используя content_id, или же она может быть указана отправителем в сообщении Load. |
| высота | целое число | Высота фотографии в пикселях (необязательный параметр ). Плеер может получить высоту самостоятельно, используя content_id, или же она может быть указана отправителем в сообщении Load. |
| creationDateTime | строка (ISO 8601) | Необязательные дата и время съемки фотографии в формате ISO 8601. Плеер может получить значение creationDateTime самостоятельно, используя content_id, или же оно может быть указано отправителем в сообщении Load. |
MediaStatus
Описывает текущее состояние медиафайла относительно сессии.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Уникальный идентификатор для воспроизведения в рамках данной конкретной сессии. Этот идентификатор устанавливается получателем при загрузке и может использоваться для идентификации конкретного экземпляра воспроизведения. Например, два воспроизведения песни "Wish you were here" в рамках одной сессии будут иметь уникальный mediaSessionId. |
| СМИ | МедиаИнформация | Необязательно (для сообщений о состоянии) Полное описание воспроизводимого контента. Возвращается в сообщениях о состоянии только в том случае, если информация о медиафайле изменилась. |
| playbackRate | плавать | Указывает, идёт ли отсчёт времени воспроизведения и с какой скоростью. Это не зависит от состояния проигрывателя, поскольку отсчёт времени может остановиться в любом состоянии. 1.0 — обычное время, 0.5 — замедленное. |
| состояние игрока | перечисление (строка) | Описывает состояние игрока одним из следующих способов:
|
| idleReason | перечисление (строка) | Если состояние игрока (playerState) равно IDLE и причина перехода в состояние IDLE известна, это свойство предоставляется. Если игрок находится в состоянии IDLE, потому что только что начал игру, это свойство не предоставляется; если игрок находится в любом другом состоянии, это свойство не должно предоставляться. Применяются следующие значения:
|
| текущее время | двойной | Текущее положение медиаплеера с момента начала воспроизведения контента, в секундах. Если это прямая трансляция, то это поле отображает время в секундах с начала события, которое должно быть известно плееру. |
| supportedMediaCommands | флаги | Флаги, описывающие, какие команды воспроизведения мультимедиа поддерживаются медиаплеером:
Комбинации описываются как суммы; например, Pause+Seek+StreamVolume+Mute == 15. |
| объем | Объем | Объем потока |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |
Команды от отправителя к получателю
Эти команды управляют медиаплеером. Все объекты customData в приведенных ниже сообщениях должны быть необязательными (т.е. приемник должен корректно работать, если данные не передаются). Это позволит корректно работать стандартным приложениям дистанционного управления.
Нагрузка
Загружает новый контент в медиаплеер.
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | ЗАГРУЗКА (только значение) |
| СМИ | МедиаИнформация | Метаданные (включая contentId) загружаемого медиафайла |
| автовоспроизведение | логический | Необязательный параметр (по умолчанию true). Если указан параметр автовоспроизведения, медиаплеер начнет воспроизведение контента после его загрузки. Даже если автовоспроизведение не указано, реализация медиаплеера может начать воспроизведение немедленно. Если воспроизведение началось, состояние плеера в ответе должно быть установлено в BUFFERING, в противном случае — в PAUSED. |
| текущее время | двойной | Необязательно. Секунды с начала воспроизведения контента. Если контент является прямым эфиром и позиция не указана, трансляция начнется с позиции в прямом эфире. |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока Загрузка не удалась Загрузка отменена |
Пауза
Приостанавливает воспроизведение текущего контента. Инициирует отправку уведомления о событии STATUS всем приложениям-отправителям.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Идентификатор медиасессии, которую необходимо приостановить. |
| requestId | целое число | Идентификатор запроса, используемый для сопоставления запроса и ответа. |
| тип | нить | ПАУЗА (только значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока |
Искать
Устанавливает текущую позицию в потоке. Запускает уведомление о событии STATUS для всех приложений-отправителей. Если указанная позиция выходит за пределы допустимого диапазона позиций для текущего контента, проигрыватель должен выбрать допустимую позицию, максимально близкую к запрошенной.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Идентификатор медиасессии, в которой задается позиция потока. |
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | ИЩИ (только значение) |
| resumeState | перечисление (строка) | Необязательный параметр. Если он не задан, статус воспроизведения не изменится; применяются следующие значения:
|
| текущее время | двойной | Необязательно. Секунды с начала воспроизведения контента. Если контент является прямым эфиром и позиция не указана, трансляция начнется с позиции в прямом эфире. |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока |
Останавливаться
Останавливает воспроизведение текущего контента. Инициирует отправку уведомления о событии STATUS всем приложениям-отправителям. После выполнения этой команды контент больше не будет загружаться, а mediaSessionId будет признан недействительным.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Идентификатор медиасессии для контента, который необходимо остановить. |
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | СТОП (только значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока |
Играть
Начинается воспроизведение контента, загруженного с помощью вызова функции загрузки; воспроизведение продолжается с текущей временной позиции.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Идентификатор медиасессии для воспроизводимого контента. |
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | ИГРАТЬ (только выгода) |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока |
Получить статус
Получает информацию о статусе медиафайлов.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Необязательный идентификатор медиасессии, для которой должен быть возвращен статус медиафайла. Если идентификатор не указан, будет предоставлен статус для всех идентификаторов медиасессий. |
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | GET_STATUS (только значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Сообщение MediaStatus отправителю, который его запросил. | Никто | Никто | Никто |
Установить громкость
Устанавливает громкость медиапотока. Используется для эффектов плавного появления/исчезания медиапотока. (Примечание: громкость приемника изменяется с помощью параметра setVolume веб-отправителя.) Громкость потока не должна использоваться совместно с ползунком громкости или кнопками регулировки громкости для управления громкостью устройства. Изменение громкости потока не приведет к отображению какого-либо пользовательского интерфейса на приемнике.
| Имя | Тип | Описание |
|---|---|---|
| mediaSessionId | целое число | Идентификатор медиасессии, для которого изменена громкость потока. |
| requestId | целое число | Идентификатор запроса для сопоставления запроса и ответа. |
| тип | нить | ОБЪЕМ (только значение) |
| объем | Объем | Объем потока |
| пользовательские данные | объект | необязательный блок данных, специфичный для приложения и определяемый приложением-отправителем. |
| Ответ | Триггеры | Трансляции | Ошибки |
|---|---|---|---|
| Никто | изменение состояния получателя | Сообщение об изменении статуса медиафайла | Недопустимое состояние игрока |
Сообщения от получателя к отправителю
Получатель отправляет два типа сообщений:
- Ошибки: Одноадресные сообщения, отправляемые при получении ответа об ошибке на запрос отправителя.
- Статус: Транслируемые сообщения.
- Последствия действия, инициированного отправителем. Будет содержать requestId запроса, вызвавшего изменение.
- Спонтанный: Например, из-за изменения, инициированного приложением-получателем. Идентификатор запроса будет равен 0.
Ошибка: Недопустимое состояние игрока
Отправляется, когда запрос отправителя не может быть выполнен, поскольку плеер находится в недопустимом состоянии. Например, если приложение еще не создало медиаэлемент.
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор запроса, вызвавшего эту ошибку. |
| тип | нить | INVALID_PLAYER_STATE (единственное значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |
Ошибка: Загрузка не удалась
Отправляется в случае сбоя запроса на загрузку. Состояние игрока будет IDLE.
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор запроса, вызвавшего эту ошибку. |
| тип | нить | LOAD_FAILED (единственное значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |
Ошибка: Загрузка отменена
Отправлено после отмены запроса на погрузку (был получен второй запрос на погрузку).
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор запроса, вызвавшего эту ошибку. |
| тип | нить | LOAD_CANCELLED (единственное значение) |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |
Ошибка: Неверный запрос
Отправляется, когда запрос недействителен (например, запрос неизвестного типа).
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор запроса, вызвавшего эту ошибку. |
| тип | нить | INVALID_REQUEST (единственное значение) |
| причина | Перечисление (строка) | Ценности:
|
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |
Статус СМИ
Отправляется после изменения состояния или после запроса статуса медиафайла. Будут отправлены только те объекты MediaStatus, которые изменились или были запрошены.
| Имя | Тип | Описание |
|---|---|---|
| requestId | целое число | Идентификатор используется для сопоставления этого ответа о статусе с запросом, который его инициировал, или равен 0, если сообщение о статусе является спонтанным (не вызвано запросом отправителя). Приложения отправителя генерируют уникальные идентификаторы запросов, выбирая случайное число и постоянно увеличивая его (они не будут использовать 0). |
| тип | нить | MEDIA_STATUS (единственное значение) |
| статус | MediaStatus [] | Массив объектов MediaStatus. ПРИМЕЧАНИЕ: элемент media в MediaStatus будет возвращен только в том случае, если он изменился. |
| пользовательские данные | объект | необязательный блок данных, специфичный для конкретного приложения, определяемый приложением-получателем. |