Servir el contenido multimedia

La ruta del contenido

GET <baseUrl>/media/<externalId>?t=<mediaToken>

Cómo se construye la dirección

El Stage construye la dirección a partir del baseUrl que sincronizaste por última vez y del externalId de la pista, y lo hace así:

• Solo se usa el origen de baseUrl: esquema, host y puerto. Una ruta en baseUrl se descarta, así que la ruta siempre es /media/… en la raíz de ese origen, y no en /music/media/… porque ahí la hayas montado.
• externalId se codifica con porcentaje en el último segmento de la ruta. Decodifícalo. Un id con un espacio o una barra llega como %20 o %2F.
• t lleva el token de media, y una vista previa añade &preview=1 (véase Responder bajo demanda).
• La dirección se resuelve cuando una canción está a punto de sonar, a partir de lo último que sincronizaste. Después el Stage la conserva mientras dure esa canción.

El certificado del host debe ser uno en el que el navegador del Stage ya confíe. El Stage es una página web y no tiene a nadie que pueda saltarse una advertencia, así que un certificado autofirmado no funciona se instale como se instale. Un proveedor en una red doméstica puede usar el nombre y el certificado descritos en Un nombre y un certificado.

Qué responder

• Rechaza un token incorrecto o ausente con 403. Un id que no tienes es un 404.
• Admite peticiones de rango. Los elementos multimedia se desplazan con ellas. Un servidor que ignora Range suele reproducir una vez y romperse en cuanto alguien mueve la barra. Las formas que envía un navegador son bytes=N- y bytes=N-M. Responde a un rango con 206, un Content-Range y un Content-Length de la parte y no del total. Responde a un rango que empieza más allá del final con 416 y Content-Range: bytes */<size>. Sin cabecera Range, responde 200 con el archivo entero. Envía Accept-Ranges: bytes en todas las respuestas.
• Envía el Content-Type correcto para el contenedor: video/mp4, video/webm, video/quicktime, audio/mpeg, audio/mp4. Un navegador a veces se recupera de uno equivocado y a veces no, y no merece la pena descubrirlo en el televisor de alguien.
• Responde a OPTIONS con un 204 y las cabeceras CORS de abajo. Las peticiones del Stage son simples, así que no se espera un preflight, pero un navegador tiene derecho a enviarlo.
• Envía Access-Control-Allow-Private-Network: true si estás en una dirección privada. Chrome no lo exige actualmente, porque en su lugar se apoya en un permiso que pide una sola vez al usuario, pero la exigencia se ha aplazado antes y la cabecera no cuesta nada.

CORS

Las cabeceras CORS son obligatorias si declaras canAnalyseAudio, y recomendables te hayas declarado o no. Un elemento <video> o <audio> normal reproduce contenido de otro origen sin ellas, que es lo que hace el Stage con un proveedor que no declara la capacidad. Declararla es lo que cambia eso, porque entonces el Stage pide el contenido en un modo que falla por completo si faltan. Véase Capacidades para saber por qué y qué sale mal.

Cuando las envíes, envíalas en toda respuesta correcta a una petición de una dirección de contenido, tanto 200 como 206, y también en un 416. No hace falta que estén en un 403 ni en un 404:

• Access-Control-Allow-Origin con el origen que preguntó (tomado de la cabecera Origin), o *. El Stage no envía credenciales, así que un comodín es aceptable. Si devuelves el origen tal cual, envía también Vary: Origin.
• Access-Control-Expose-Headers: Content-Length, Content-Range.
• Access-Control-Allow-Methods: GET, HEAD, OPTIONS y Access-Control-Allow-Headers: Range en la respuesta a OPTIONS.

Si la dirección redirige, cada salto tiene que hacer lo mismo.

El token de media

El token de media es tuyo. Lo guardamos, cifrado, y lo ponemos en la dirección que se le da al Stage, que es como el Stage te demuestra que la pantalla tiene permiso para pedir. Evita que cualquier otra persona de la misma red recorra tu biblioteca adivinando ids, lo que en un wifi compartido o de invitados es una preocupación real y no teórica.

Rotarlo, por ejemplo en cada reinicio, está bien, porque la siguiente sincronización nos da el nuevo. La consecuencia es que un Stage que ya tenga la dirección de la canción que está sonando recibirá un 403 en su siguiente petición de rango, así que un reinicio interrumpe lo que hay en pantalla, y también una canción que empiece antes de que haya llegado la primera sincronización tras el reinicio. Envía esa sincronización lo antes que puedas. Las canciones que se resuelvan después usan el token nuevo y suenan.

Qué ve una persona cuando falla

Hay dos fallos distintos, y la sala los ve de forma distinta.

Si el servicio no tiene ninguna dirección que dar para una pista, porque la biblioteca se borró o nunca se sincronizó, el Stage dice que la biblioteca que contiene la canción no está accesible, y espera. No salta, porque recorrer una cola en silencio esconde la causa.

Si el servicio da una dirección y luego el navegador no puede cargarla, el elemento multimedia notifica un error y el Stage salta la canción y pasa a la siguiente, sin nada en pantalla que diga por qué. Un permiso denegado, un ordenador dormido, una red distinta, un certificado en el que el navegador no confía, un token incorrecto y un archivo que el navegador no sabe decodificar se ven exactamente igual desde la sala: canciones que empiezan y se van. Esa es una razón para responder a un token incorrecto con un 403 sin más. Permite distinguir los casos cuando lees tus propios registros.

Formatos

El Stage reproduce a través de un elemento multimedia del navegador, así que lo que suena es lo que el navegador abre. MP4/H.264, WebM y MOV funcionan directamente. MKV, AVI, WMV y FLV no, y tampoco CDG+MP3 — y CDG en particular es el formato real de los discos de karaoke, habitual en bibliotecas reales.

Un contenedor es solo la mitad. Un navegador abre un archivo únicamente si también puede decodificar lo que lleva dentro:

• MP4 y MOV se reproducen en todas partes con vídeo H.264 y audio AAC. HEVC (H.265) se reproduce en algunos dispositivos y en otros no. Un .mov de una cámara o de un editor suele ser uno de esos.
• WebM significa vídeo VP8 o VP9 con audio Vorbis u Opus.
• El audio en MP3, y AAC en un M4A, se reproduce en todas partes. Apple Lossless en un M4A no se reproduce en todos los navegadores.

Nada en el servicio mira dentro de un archivo. El bridge decide solo por la extensión, así que un .mp4 que declara reproducible puede aun así fallar en un televisor concreto. Si un archivo es reproducible es un juicio tuyo, y tú eres quien está en posición de hacerlo.

Si tu fuente tiene archivos que el navegador no abrirá, transcodifica. Hasta que puedas, dilo pista por pista con playable: false en todo lo que el navegador no vaya a abrir.

Una pista marcada así sigue catalogada, y su dueño la sigue viendo en la página de la biblioteca marcada como una que no se reproducirá. Se deja fuera de explorar y de la búsqueda, para que nadie pueda ponerla en la cola y verla fallar en la pared. Eso es mejor que las otras dos alternativas: ofrecerla y fallar delante de una sala, o descartarla en silencio y dejar a alguien preguntándose dónde está la mitad de su colección.

Omitir el indicador significa reproducible. Un proveedor escrito antes de que esto existiera se toma por su palabra en lugar de ponerse en duda a partir de un nombre de archivo que nunca se nos mostró.