Os apps de transmissão do Google Cast controlam a reprodução no dispositivo receptor enviando mensagens no formato JSON para o app receptor. Da mesma forma, o destinatário envia mensagens de volta para o remetente, também em JSON. As mensagens podem ser comandos do remetente que alteram o estado do player, respostas do receptor ou estruturas de dados que descrevem a mídia do aplicativo receptor.
De acordo com os Termos de Serviço adicionais do desenvolvedor do SDK do Google Cast, um app de mídia do Google Cast precisa usar essas mensagens conforme definido aqui para controlar a reprodução de mídia no receptor. Isso oferece ao app de música uma experiência do usuário consistente em todas as plataformas e garante que um app do Google Cast ofereça suporte a casos de uso novos e futuros. Essas estruturas também aceitam dados personalizados, quando adequado, e um aplicativo pode definir as próprias mensagens para comandos não compatíveis com o SDK.
O namespace das mensagens de reprodução de mídia é definido como urn:x-cast:com.google.cast.media.
Observação: as mensagens e estruturas nesta especificação têm um tamanho máximo implícito determinado pelo tamanho máximo de uma mensagem de transporte. Não há limite para campos individuais. Atualmente, o tamanho máximo das mensagens de transporte é de 64 KBytes.
Estruturas de dados de namespace comuns
Um superconjunto de estruturas de dados usado por todos os artefatos de namespace de mídia é definido em um namespace comum.
Imagem
Essa é a descrição de uma imagem, incluindo uma pequena quantidade de metadados para permitir que o aplicativo remetente escolha imagens, dependendo de como elas serão renderizadas.
A altura e a largura são opcionais em apenas um item em uma matriz de imagens. Por exemplo, se um único item for retornado, eles serão opcionais. Se houver dois itens retornados, um deles precisará especificar a altura e a largura, mas o remetente poderá escolher a opção "padrão" se não gostar da opção transmitida com parâmetros específicos.
| Nome | Tipo | Descrição |
|---|---|---|
| url | URI | URI da imagem |
| height (altura) | número inteiro | opcional : altura da imagem |
| largura | número inteiro | opcional : largura da imagem |
Volume
O volume do stream de mídia. Usado para efeitos de aparecimento gradual e esmaecimento no stream de mídia. Observação: o volume do sistema é alterado usando as APIs do remetente. O volume do stream não pode ser usado com o controle deslizante ou os botões de volume para controlar o volume do dispositivo. Pelo menos um dos parâmetros a seguir precisa ser transmitido para mudar o volume do stream.
| Nome | Tipo | Descrição |
|---|---|---|
| nível | dupla | Opcional Nível de volume do stream atual como um valor entre 0,0 e 1,0, em que 1,0 é o volume máximo. |
| silenciado | boolean | opcional : se o dispositivo de transmissão está com o som desativado, independentemente do nível de volume. |
Estruturas de dados de namespace de mídia
Essas mensagens descrevem o estado do player de mídia. O namespace é urn:x-cast:com.google.cast.media.
MediaInformation
Essa estrutura de dados descreve um fluxo de mídia.
| Nome | Tipo | Descrição |
|---|---|---|
| contentId | string | Identificador específico do serviço do conteúdo carregado atualmente pelo player de mídia. Trata-se de uma string de formato livre e específica para o aplicativo. Na maioria dos casos, esse será o URL da mídia, mas o remetente pode optar por transmitir uma string que o destinatário possa interpretar corretamente. Comprimento máximo: 1.000 |
| streamType | enumeração (string) |
Descreve o tipo de artefato de mídia como uma das seguintes opções:
|
| contentType | string | Tipo de conteúdo MIME da mídia reproduzida |
| metadata | objeto | Opcional : o objeto de metadados de mídia, que pode ser um dos seguintes: |
| duração | dupla | opcional : duração da transmissão em segundos |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente ou receptor. |
GenericMediaMetadata
Descreve um artefato de mídia genérico.
| Nome | Tipo | Descrição |
|---|---|---|
| metadataType | número inteiro | 0 (o único valor) |
| title | string | opcional : título descritivo do conteúdo. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| legenda | string | opcional : subtítulo descritivo do conteúdo. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| imagens | Imagem[] | opcional : matriz de URLs para uma imagem associada ao conteúdo. O valor inicial do campo pode ser informado pelo remetente na mensagem Load. Deve fornecer os tamanhos recomendados |
| releaseDate | string (ISO 8601) | opcional : data e hora ISO 8601 em que esse conteúdo foi lançado. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
MovieMediaMetadata
Descreve um artefato de mídia de filme.
| Nome | Tipo | Descrição |
|---|---|---|
| metadataType | número inteiro | 1 (o único valor) |
| title | string | opcional : título descritivo do conteúdo. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| legenda | string | opcional : subtítulo descritivo do conteúdo. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| Studio | string | opcional : o estúdio que lançou o conteúdo. O player pode recuperar o Studio de forma independente usando content_id ou pode ser fornecido pelo remetente na mensagem Load |
| imagens | Imagem[] | opcional : matriz de URLs para uma imagem associada ao conteúdo. O valor inicial do campo pode ser informado pelo remetente na mensagem Load. Deve fornecer os tamanhos recomendados |
| releaseDate | string (ISO 8601) | opcional : data e hora ISO 8601 em que esse conteúdo foi lançado. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
TvShowMediaMetadata
Descreve um artefato de mídia de episódio de programa de televisão.
| Nome | Tipo | Descrição |
|---|---|---|
| metadataType | número inteiro | 2 (o único valor) |
| seriesTitle | string | opcional : título descritivo da série de TV. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| legenda | string | opcional : subtítulo descritivo do episódio de TV. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| temporada | número inteiro | opcional Número da temporada do programa de TV |
| episódio | número inteiro | opcional : número do episódio (na temporada) do programa de TV |
| imagens | Imagem[] | opcional : matriz de URLs para uma imagem associada ao conteúdo. O valor inicial do campo pode ser informado pelo remetente na mensagem Load. Deve fornecer os tamanhos recomendados |
| originalAirDate | string (ISO 8601) | opcional : data e hora ISO 8601 de lançamento do episódio. O player pode recuperar o originalAirDate de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
MusicTrackMediaMetadata
Descreve um artefato de mídia de faixa de música.
| Nome | Tipo | Descrição |
|---|---|---|
| metadataType | número inteiro | 3 (o único valor) |
| albumName | string | opcional Álbum ou coleção de onde a música foi tirada. O player pode recuperar albumName de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| title | string | opcional : nome da faixa (por exemplo, título da música). O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| albumArtist | string | opcional : nome do artista associado ao álbum que contém a música. O player pode recuperar o albumArtist de maneira independente usando o content_id ou pode ser fornecido pelo remetente na mensagem Load |
| artista | string | opcional Nome do artista associado à faixa de mídia. O player pode recuperar o artista de forma independente usando content_id ou pode ser fornecido pelo remetente na mensagem Load |
| Composer | string | opcional : nome do compositor associado à faixa de mídia. O player pode recuperar o composer de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| trackNumber | número inteiro | opcional Número da faixa do álbum |
| discNumber | número inteiro | opcional Número do volume (por exemplo, um disco) do álbum |
| imagens | Imagem[] | opcional : matriz de URLs para uma imagem associada ao conteúdo. O valor inicial do campo pode ser informado pelo remetente na mensagem Load. Deve fornecer os tamanhos recomendados |
| releaseDate | string (ISO 8601) | opcional : data e hora ISO 8601 em que esse conteúdo foi lançado. O player pode recuperar a data de lançamento de forma independente usando o content_id ou ela pode ser fornecida pelo remetente na mensagem Load |
PhotoMediaMetadata
Descreve um artefato de mídia fotográfica.
| Nome | Tipo | Descrição |
|---|---|---|
| metadataType | número inteiro | 4 (o único valor) |
| title | string | opcional Título da foto. O player pode recuperar o título de forma independente usando content_id ou ele pode ser fornecido pelo remetente na mensagem Load |
| artista | string | opcional : nome do fotógrafo. O player pode recuperar o artista de forma independente usando content_id ou pode ser fornecido pelo remetente na mensagem Load |
| local | string | opcional Local verbal onde a foto foi tirada, por exemplo, "Madri, Espanha". O player pode recuperar a localização de forma independente usando content_id ou pode ser fornecida pelo remetente na mensagem Load |
| latitude | dupla | opcional : é o valor de latitude geográfica do local onde a foto foi tirada. O player pode recuperar a latitude de forma independente usando content_id ou essa informação pode ser fornecida pelo remetente na mensagem Load |
| longitude | dupla | opcional : valor de longitude geográfica do local onde a foto foi tirada. O player pode recuperar a longitude de forma independente usando content_id ou essa informação pode ser fornecida pelo remetente na mensagem Load |
| largura | número inteiro | opcional Largura em pixels da foto. O player pode recuperar a largura de forma independente usando content_id ou essa informação pode ser fornecida pelo remetente na mensagem Load |
| height (altura) | número inteiro | opcional Altura em pixels da foto. O player pode recuperar a altura de forma independente usando content_id ou essa informação pode ser fornecida pelo remetente na mensagem Load |
| creationDateTime | string (ISO 8601) | opcional : data e hora ISO 8601 em que a foto foi tirada. O player pode recuperar createDateTime de forma independente usando content_id ou essa informação pode ser fornecida pelo remetente na mensagem Load |
MediaStatus
Descreve o status atual do artefato de mídia em relação à sessão.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID exclusivo da reprodução dessa sessão específica. Esse ID é definido pelo receptor em LOAD e pode ser usado para identificar uma instância específica de uma reprodução. Por exemplo, duas reproduções de "Gostaria que você estivesse aqui" na mesma sessão teriam um mediaSessionId exclusivo. |
| media | MediaInformation | opcional (para mensagens de status) Descrição completa do conteúdo que está sendo reproduzido. Só será retornada em uma mensagem de status se a MediaInformation tiver sido alterada. |
| playbackRate | float | Indica se o tempo de mídia está progredindo e a que velocidade. Isso é independente do estado do player, já que o tempo de mídia pode parar em qualquer estado. 1,0 é o horário normal e 0,5 é câmera lenta |
| playerState | enum (string) | Descreve o estado do player como um dos seguintes:
|
| idleReason | enum (string) | opcional Se playerState for IDLE e o motivo pelo qual ele se tornou IDLE for conhecido, essa propriedade será fornecida. Se o player estiver ocioso porque acabou de ser iniciado, essa propriedade não será fornecida. Se o player estiver em qualquer outro estado, essa propriedade não deverá ser fornecida. Os seguintes valores se aplicam:
|
| currentTime | dupla | É a posição atual do player de mídia desde o início do conteúdo, em segundos. Se for um conteúdo de transmissão ao vivo, este campo representa o tempo em segundos desde o início do evento que deve ser conhecido pelo player. |
| supportedMediaCommands | flags | Sinalizações que descrevem os comandos de mídia compatíveis com o player:
As combinações são descritas como somas. Por exemplo, Pause+Seek+StreamVolume+Mute == 15. |
| volume | Volume | Volume de stream |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |
Comandos do emissor para o receptor
Esses comandos controlam o player de mídia. Todos os objetos customData nas mensagens abaixo precisam ser opcionais (ou seja, o receptor deve se degradar corretamente se os dados não são transmitidos). Isso permitirá que apps genéricos de controle remoto funcionem corretamente.
Carregar
Carrega o novo conteúdo no player de mídia.
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | LOAD (somente valor) |
| media | MediaInformation | Metadados (incluindo contentId) da mídia a ser carregada |
| reprodução automática | boolean | Opcional (o padrão é verdadeiro) Se o parâmetro de reprodução automática for especificado, o player de mídia começará a reproduzir o conteúdo quando ele for carregado. Mesmo que a reprodução automática não seja especificada, a implementação do player de mídia pode iniciar a reprodução imediatamente. Se a reprodução for iniciada, o estado do player na resposta deverá ser definido como BUFFERING. Caso contrário, ele deve ser definido como PAUSED |
| currentTime | dupla | opcional : segundos desde o início do conteúdo. Se o conteúdo for ao vivo e a posição não for especificada, a transmissão vai começar na posição ao vivo |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido Falha no carregamento Carregamento cancelado |
Pausar
Pausa a reprodução do conteúdo atual. Aciona uma notificação de evento STATUS para todos os apps remetente.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID da sessão de mídia a ser pausada |
| requestId | número inteiro | ID da solicitação, a ser usada para correlacionar solicitação/resposta |
| tipo | string | PAUSE (somente valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido |
Procurar
Define a posição atual no stream. Aciona uma notificação de evento STATUS para todos os apps remetente. Se a posição fornecida estiver fora do intervalo de posições válidas para o conteúdo atual, o player deverá escolher uma posição válida o mais próximo possível da posição solicitada.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID da sessão de mídia em que a posição da transmissão está definida |
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | buscar (único valor) |
| resumeState | enum (string) | Opcional : se essa opção não for definida, o status da reprodução não mudará. Os seguintes valores se aplicam:
|
| currentTime | dupla | opcional : segundos desde o início do conteúdo. Se o conteúdo for ao vivo e a posição não for especificada, a transmissão vai começar na posição ao vivo |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido |
Parar
Interrompe a reprodução do conteúdo atual. Aciona uma notificação de evento STATUS para todos os apps remetente. Depois desse comando, o conteúdo não será mais carregado, e o mediaSessionId será invalidado.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID da sessão de mídia do conteúdo a ser interrompido |
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | STOP (único valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido |
Jogar
Inicia a reprodução do conteúdo que foi carregado com a chamada de carregamento. A reprodução continua a partir da posição de tempo atual.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID da sessão de mídia do conteúdo a ser reproduzido |
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | PLAY (somente valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido |
Obter status
Recupera o status da mídia.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | Opcional : ID da sessão de mídia da mídia para a qual o status precisa ser retornado. Se nenhum for fornecido, o status de todos os IDs de sessão de mídia será fornecido. |
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | GET_STATUS (único valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Mensagem MediaStatus ao remetente que a solicitou | Nenhum | Nenhum | Nenhum |
SetVolume
Define o volume do fluxo de mídia. Usado para efeitos de aparecimento gradual e esmaecimento no stream de mídia. Observação: o volume do receptor é alterado usando o setVolume do remetente da Web. O volume do stream não pode ser usado com o controle deslizante ou os botões de volume para controlar o volume do dispositivo. Uma mudança no volume do stream não vai acionar nenhuma interface no receptor.
| Nome | Tipo | Descrição |
|---|---|---|
| mediaSessionId | número inteiro | ID da sessão de mídia da mídia para a qual o volume de stream é alterado |
| requestId | número inteiro | ID da solicitação, para correlacionar solicitação e resposta |
| tipo | string | VOLUME (único valor) |
| volume | Volume | Volume de stream |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo remetente |
| Resposta | Gatilhos | Transmissões | Erros |
|---|---|---|---|
| Nenhum | Mudança de estado do receptor | Uma mensagem de alteração de status de mídia | Estado do player inválido |
Mensagens do destinatário para o remetente
O receptor envia dois tipos de mensagem:
- Erros: mensagens Unicast enviadas quando há uma resposta de erro para uma solicitação do remetente.
- Status: transmitir mensagens.
- Consequência de uma ação iniciada pelo remetente. Contém o requestId da solicitação que causou a alteração.
- Espontâneo: por exemplo, devido a uma mudança acionada pelo app receptor. O RequestId será 0.
Erro: estado do player inválido
É enviado quando a solicitação do remetente não pode ser atendida porque o player não está em um estado válido. Por exemplo, se o app ainda não tiver criado um elemento de mídia.
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID da solicitação que gerou o erro |
| tipo | string | INVALID_PLAYER_STATE (único valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |
Erro: falha no carregamento
É enviado quando a solicitação de carregamento falha. O estado do player ficará inativo.
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID da solicitação que gerou o erro |
| tipo | string | LOAD_FAILED (único valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |
Erro: carregamento cancelado
Enviado quando a solicitação de carregamento foi cancelada (uma segunda solicitação de carregamento foi recebida).
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID da solicitação que gerou o erro |
| tipo | string | LOAD_CANCELLED (único valor) |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |
Erro: solicitação inválida
É enviado quando a solicitação é inválida (um tipo desconhecido, por exemplo).
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID da solicitação que gerou o erro |
| tipo | string | INVALID_REQUEST (único valor) |
| motivo | Enumeração (string) | Valores:
|
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |
Status da mídia
Enviado após uma mudança de estado ou após uma solicitação de status de mídia. Somente os objetos MediaStatus que foram alterados ou solicitados serão enviados.
| Nome | Tipo | Descrição |
|---|---|---|
| requestId | número inteiro | ID usado para correlacionar essa resposta de status com a solicitação que a originou ou 0 se a mensagem de status for espontânea (não acionada por uma solicitação do remetente). Os aplicativos de envio geram IDs de solicitação exclusivos selecionando e aumentando continuamente um número aleatório (eles não usarão 0). |
| tipo | string | MEDIA_STATUS (único valor) |
| status | MediaStatus[] | Matriz de objetos de status de mídia. OBSERVAÇÃO: o elemento de mídia no MediaStatus só será retornado se tiver sido alterado. |
| customData | objeto | opcional blob de dados específico do aplicativo definido pelo aplicativo receptor |