Perfiles de dispositivo¶

No todos los dispositivos de los espectadores reproducen todas las pistas de un stream. Un decodificador no puede con 720p60, un televisor no reproduce HEVC, un reproductor de webOS falla con los subtítulos. Un perfil de dispositivo oculta a ese dispositivo las pistas sobrantes y no afecta al resto de los espectadores.

Un perfil es un registro con nombre y tres partes:

cómo reconocer el dispositivo — por User-Agent, por un encabezado de la solicitud o por un parámetro de la URL;
dónde se aplica el perfil — modos de entrega y streams;
qué pistas conservar — límites de vídeo, audio y subtítulos.

Hay un único conjunto de perfiles para todo el clúster. Lo guarda central y lo entrega a cada streamer junto con el resto de la configuración; la decisión la toma el streamer al que llegó el espectador, sin consultar a central.

Un perfil solo reduce: quita pistas y nunca añade. No es un control de acceso: un espectador que falsifica un encabezado recibe el conjunto que corresponde a ese encabezado, y «4K solo para premium» es tarea de la política de acceso.

De qué se compone un perfil¶

La sección Perfiles de dispositivo de la consola muestra los perfiles en el orden en que el streamer los prueba. Haga clic en un perfil para abrir su ficha.

La sección de perfiles: orden de prueba, un perfil solo por URL y un perfil que un streamer no aplicó

En el encabezado de la ficha se ve:

el nombre del perfil y su URL p/<nombre>/;
la prioridad, por ejemplo prioridad 10, o la marca solo por URL en un perfil sin condiciones;
la marca modificado si el perfil tiene cambios sin guardar.

Para crear un perfil, pulse Añadir perfil, escriba el nombre en el diálogo Nuevo perfil y pulse Añadir perfil. El nombre del perfil se compone de letras latinas minúsculas, dígitos y los caracteres ., _, -, tiene como máximo 64 caracteres y empieza por letra o dígito. El nombre forma parte de la URL p/<nombre>/ (vea URL bajo perfil). Puede haber como máximo 64 perfiles: con 64, Añadir perfil no está disponible. Un perfil nuevo, como cualquier cambio, se aplica solo después de Guardar (vea edición).

Cómo reconocer el dispositivo¶

Un perfil se elige si coincide al menos una condición:

User-Agent contiene — una subcadena del encabezado User-Agent, sin distinguir mayúsculas: Roku coincide con Roku/DVP-14.5.
Encabezados de la solicitud — el nombre de un encabezado y una subcadena de su valor, sin distinguir mayúsculas en ninguno de los dos. Así se reconoce un dispositivo por un encabezado que pone su middleware (X-CDN-DEV-MODEL: 4800X) o por una clase de dispositivo que ya trae la CDN (CloudFront-Is-SmartTV-Viewer: true, X-UA-Device). El streamer no tiene una base de dispositivos integrada.
Parámetros de la URL — el nombre de un parámetro y una lista de valores separados por comas. El parámetro coincide si su valor completo es igual a uno de los valores, distinguiendo mayúsculas: ?device_profile=arris coincide con el valor arris, pero no con arris-4205 ni con Arris. Los valores se escriben decodificados: + en la URL es un espacio, así que ?p=S10+ coincide con el valor S10 (con espacio), y el valor S10+ solo coincide con ?p=S10%2B.

Una solicitud sin User-Agent no coincide con una condición por User-Agent.

Un perfil sin ninguna condición lleva la marca solo por URL: el streamer lo elige solo cuando la propia URL nombra el perfil (vea URL bajo perfil).

Dónde se aplica¶

Prioridad — obligatoria y única en los perfiles con condiciones: el streamer los prueba en orden ascendente y toma el primero que encaja. En un perfil sin condiciones no tiene efecto.
Modos de entrega — a qué solicitudes se aplica el perfil. Por defecto, los tres modos.
Etiquetas de streams y Nombres de streams — a qué streams se aplica el perfil: un stream entra si lleva al menos una de las etiquetas o si está nombrado. Vacío significa todos los streams. Entre todos los perfiles se pueden nombrar como máximo 1000 streams; para muchos streams use una etiqueta.

Modos de entrega:

En directo — solicitud del stream en directo;
Archivo — solicitud con from;
Rebobinado — URL rewind/<segundos>/.

Las Etiquetas de streams se introducen de una en una: escriba la etiqueta y pulse Enter. Una etiqueta se compone de letras latinas, dígitos y los caracteres _, ., - y tiene como máximo 40 caracteres. La consola comprueba la etiqueta en el momento: una etiqueta de otra forma no se añade y aparece un error bajo el campo. Una etiqueta que ya está en la lista no se añade por segunda vez.

Qué pistas conservar¶

Los límites se agrupan por tipo de pista, y cada grupo solo juzga las pistas de su tipo:

Vídeo — Códecs o Todos los códecs excepto, Ancho, Alto, Fotogramas por segundo.
Audio — Códecs o Todos los códecs excepto, Idiomas o Todos los idiomas excepto, el interruptor No entregar audio.
Subtítulos — Idiomas o Todos los idiomas excepto, el interruptor No entregar subtítulos.

Los campos de una misma sección dependen unos de otros:

el campo Códecs relleno desactiva Todos los códecs excepto, y al revés: central no acepta las dos listas en una misma sección;
del mismo modo, el campo Idiomas relleno desactiva Todos los idiomas excepto, y al revés;
el interruptor No entregar audio o No entregar subtítulos, activado, quita todas las pistas de ese tipo y oculta los demás campos de la sección.

Una pista se conserva si cumple todos los límites de su grupo; dentro de un mismo límite basta con coincidir con cualquier valor. Ancho, alto y fotogramas por segundo se escriben separados por comas, como valores exactos y rangos; un rango puede dejar abierto uno de sus extremos:

1080, 720          exactamente 1080 o exactamente 720
..720              como máximo 720
720..              como mínimo 720
480..1080          de 480 a 1080, ambos incluidos
..30               como máximo 30 fotogramas por segundo
25, 29.97          frecuencia como entero o como decimal con punto
30000/1001         frecuencia como fracción

Un límite no quita una pista cuya propiedad limitada se desconoce (sin frecuencia de fotogramas, sin idioma): no hay nada que juzgar. Los idiomas se comparan por su etiqueta estándar: eng en la descripción de la pista y en en el perfil son el mismo idioma; und («no determinado») cuenta como pista sin idioma.

Un perfil sin ningún límite se elige, pero no quita nada.

La ficha de un perfil: condiciones, alcance y límites de pistas

Cómo se elige el perfil¶

El streamer elige el perfil en cada solicitud de un master playlist HLS (fMP4 y MPEG-TS, con y sin LL-HLS) y de un manifiesto DASH, en todos los modos de entrega:

En directo;
Archivo;
Rebobinado.

La elección sigue estos pasos:

Si la URL contiene un segmento de perfil p/<nombre>/, se elige el perfil nombrado y las condiciones no se comprueban.
Si no, el streamer prueba los perfiles con condiciones por prioridad ascendente y toma el primero cuya condición coincidió y cuyo alcance cubre el modo de entrega y el stream.

A cada solicitud se aplica exactamente un perfil: los límites de perfiles distintos no se suman. Si no se elige ningún perfil, el espectador recibe el conjunto completo de pistas, exactamente el playlist que se entrega sin perfiles.

La pista quitada desaparece del master junto con su variante o su rendition; un grupo de audio o de subtítulos que se queda vacío desaparece entero. Si el perfil quitó la pista de audio por defecto, pasa a serlo la primera pista que queda en el mismo grupo: un grupo son las pistas de un mismo códec (vea audio en distintos códecs).

Audio en distintos códecs en HLS¶

El master HLS agrupa las pistas de audio por códec. En un stream con AAC y AC-3, el master da al reproductor dos grupos de audio, aac y ac3, y empareja cada calidad de vídeo con cada uno de ellos. Un reproductor sin decodificador AC-3 omite las variantes del grupo ac3 y reproduce AAC en lugar de perder el stream entero.

Un perfil cuya sección Audio tiene solo aac en Códecs quita AC-3 por completo: en el master no quedan ni el grupo ac3 ni sus variantes.

El reproductor ofrece al espectador los idiomas del grupo que reproduce. Un idioma que solo existe en AC-3 no lo verá un reproductor sin decodificador AC-3.

URL bajo perfil¶

La decisión se toma una vez, en el master playlist, y luego viaja en la URL. Un master cuyo perfil se eligió por condiciones dirige al reproductor a los playlists hijos bajo el segmento del perfil:

/playback/v/<stream>/index.m3u8                     solicitud del reproductor
/playback/v/<stream>/p/<perfil>/variant/v2/...      adonde dirige el master

Los playlists, partes y segmentos bajo p/<perfil>/ no miran los encabezados ni los parámetros de la solicitud y son iguales para cualquier espectador de esa URL. El playlist de una pista que el perfil quitó responde 404 bajo p/. Sin el segmento de perfil, el playlist de una pista se entrega a cualquier espectador: las condiciones solo se comprueban en el master.

La URL con segmento de perfil también se puede dar directamente al reproductor: así elige el perfil una vitrina o un middleware que ya conoce el dispositivo:

/playback/v/<stream>/p/<perfil>/index.m3u8
/playback/v/<stream>/p/<perfil>/Manifest.mpd
/playback/v/<stream>/p/<perfil>/ts/index.m3u8
/playback/v/<stream>/p/<perfil>/rewind/600/index.m3u8

Un perfil que el streamer no conoce (eliminado, renombrado o el streamer aún no aplicó el cambio), o cuyo alcance no cubre la solicitud, no quita nada: la URL bajo él entrega el conjunto completo, sin error.

Encabezados del intermediario y redirección. Cuando central hace de proxy de la solicitud, pasa al streamer los encabezados del reproductor. Cuando central responde con una redirección a la dirección pública del streamer, el encabezado que puso un intermediario delante de central (CDN, middleware) no llega al streamer: el reproductor no lo repite. En ese esquema elija el perfil con la URL p/<perfil>/.

URL de Flussonic¶

Una URL de master al estilo antiguo (/<stream>/index.m3u8?device_profile=arris) redirige al master /streaming/v/<stream>/index.m3u8 con los mismos parámetros, y el perfil se elige como siempre. Una URL de una sola pista (/<stream>/tracks-v1/index.m3u8) lleva directamente al playlist de esa pista, sin perfil.

Catena no ejecuta la selección de pistas por número de Flussonic —el parámetro filter.tracks y las URL con un conjunto de pistas como tracks-v1a1/index.m3u8—: sus números de pista son otros, y el espectador recibe el conjunto completo. Cree un perfil para ese dispositivo; el contador device_profile_track_numbers_total (vea el diagnóstico) muestra cuántas de esas solicitudes no cubre ningún perfil.

DASH¶

En DASH la decisión también se toma en el manifiesto: el perfil quita los Representation con pistas que no encajan, y un AdaptationSet que se queda sin ningún Representation desaparece entero. Un manifiesto elegido por condiciones deja las URL de los segmentos en la raíz del stream; un manifiesto bajo p/<perfil>/ apunta a los segmentos bajo el mismo segmento de perfil.

El reproductor vuelve a leer el manifiesto DASH en directo, y cada relectura elige el perfil de nuevo, según la versión vigente de los perfiles. Editar un perfil durante la reproducción puede quitar el Representation que el reproductor está reproduciendo, y muchos reproductores se detienen ahí. Haga los cambios radicales con un perfil nuevo (vea edición).

DASH no tiene rebobinado: un perfil que solo se aplica en Rebobinado no afecta al manifiesto.

Resultado vacío¶

Si tras el filtrado no queda ninguna pista del tipo principal —vídeo, o audio en un stream sin vídeo—, el streamer responde al master con 400 y el código device_profile_empty y escribe un aviso en su registro. El espectador no recibe el conjunto completo: es justo lo que el perfil ocultaba al dispositivo. Tampoco se entrega solo el audio de un stream con vídeo: el reproductor del dispositivo no aceptaría ese master como vídeo.

La URL p/<perfil>/ responde igual: lo verá la vitrina que puso esa URL. Un resultado vacío se corrige con el alcance del perfil (etiquetas, modos) o con límites más suaves.

Edición, eliminación y cambio de nombre¶

El botón Eliminar de la ficha elimina el perfil y Renombrar le cambia el nombre. Un perfil nuevo, una eliminación y un cambio de nombre, como los cambios de campos, se aplican solo después de Guardar: hasta entonces solo existen en el formulario. El botón Cancelar descarta todos los cambios sin guardar, incluidos los campos incompletos.

El botón Guardar envía solo los campos modificados. Si los perfiles se editaron en paralelo, el formulario muestra un conflicto; sus cambios siguen en el formulario: Mostrar lo actual vuelve a cargar el documento sin sus cambios y Trasladar mis cambios los aplica a la versión actual. El resultado queda en el formulario sin guardar: revíselo —por ejemplo, un perfil que otro operador eliminó mientras usted lo editaba vuelve solo con sus campos— y guarde. Mientras el formulario tenga un campo incompleto (un valor de ancho, alto o fotogramas por segundo que no se puede interpretar, una condición sin nombre o sin valor, un nombre repetido), Guardar no está disponible.

Un cambio llega a los streamers sin reinicio y sin recalcular la colocación. Un reproductor HLS lee el master pocas veces, así que un cambio que oculta la pista que está reproduciendo provoca un 404 en el playlist de esa pista, y el reproductor cambia a otra. En DASH el manifiesto en directo se relee, y el cambio se aplica de inmediato. Por eso:

un cambio pequeño (estrechar un rango, añadir un códec a Todos los códecs excepto): edite el perfil;
un cambio radical (quitar toda una calidad, cambiar el códec): cree un perfil con otro nombre y pase a él las condiciones o las URL de la vitrina.

Cambiar el nombre equivale a eliminar y crear. Los reproductores que abrieron el stream con el nombre anterior reciben el conjunto completo de pistas hasta que vuelvan a leer el master. Eliminar funciona igual: la URL bajo un perfil eliminado entrega todo.

Si un perfil no se aplica¶

Un streamer puede no aplicar un perfil si central guardó un valor que la versión del streamer no conoce. Los demás perfiles y el resto de la configuración del streamer se aplican igualmente. Dónde se ve:

en la sección Perfiles de dispositivo: la marca No aplicado en los streamers en el encabezado de la ficha, con los nombres de los streamers, el motivo entre paréntesis y la ruta hasta el campo, por ejemplo e1 (parse) video.codecs[1]; el nombre lleva a la página del streamer. La ficha desplegada muestra los textos de rechazo que enviaron los streamers;
en la página del streamer: un bloque junto al error de aplicación de la configuración, con el nombre del perfil, el motivo, la ruta hasta el campo y el mensaje;
en la API: el campo rejected_profiles en GET /central/api-v4/nodes/stats;
en las métricas del streamer: device_profile_rejected{reason}.

Motivos:

parse — un campo no se pudo interpretar: valor o tipo desconocido;
invalid — el perfil se interpretó, pero no pasó la validación;
limit — el perfil supera los 64.

Un streamer cuya versión no conoce los perfiles en absoluto entrega todas las pistas a cualquier espectador, y central responde con éxito a la edición de un perfil. La consola lo avisa en dos lugares:

en la sección Perfiles de dispositivo: un aviso común sobre la lista, «Los perfiles no tienen efecto en los streamers cuya versión no los admite…», con enlaces a esos streamers;
en la página del streamer: la nota «Los perfiles no tienen efecto en este streamer: su versión no los admite…».

El aviso aparece solo cuando el documento de perfiles tiene al menos un perfil. No se muestra para los streamers revocados ni para un streamer que aún no aplicó la configuración desde que arrancó.

La página del streamer: un perfil que el streamer no aplicó, con el motivo y la ruta al campo

Actualización y vuelta atrás¶

Cree los perfiles después de actualizar todos los streamers. Un streamer de la versión anterior no conoce las URL p/ y les responde 404 cuando el master vino de un streamer actualizado y el playlist hijo de uno antiguo.
Volver central a una versión sin perfiles los desactiva en todo el clúster hasta que regrese: los streamers reciben la configuración sin perfiles. El documento de perfiles se queda en la base de datos, y al regresar central lo entrega sin editarlo.
Volver central una versión atrás no rompe la entrega: los streamers reciben los perfiles tal cual. Un campo que solo conoce la versión nueva estorba solo a la edición que contiene ese campo: esa edición responde 422. Un valor desconocido (por ejemplo, un códec nuevo) hace que cualquier edición del documento responda 422 hasta que se elimine ese valor.
Tras volver central atrás, guarde la config de cada streamer con cualquier cambio: si no, un streamer que estaba desconectado durante la vuelta atrás puede quedarse con su configuración anterior.

Limitaciones¶

Los fotogramas por segundo no limitan el archivo: la descripción de la grabación no los incluye, y una propiedad desconocida no quita la pista. En directo y en rebobinado el límite funciona; alto, ancho y códec funcionan también en el archivo.
Como máximo 64 perfiles y 1000 nombres de streams en los alcances de todos los perfiles.
El perfil se aplica solo a HLS (incluidos LL-HLS y MPEG-TS) y a DASH; no afecta a la entrega que se enumera abajo.
No existe el formato 720p60 de Flussonic: alto y frecuencia son límites independientes, y «quitar 720p60, dejar 1080p60» no se puede expresar con un solo perfil.

Entrega a la que el perfil no se aplica:

MSE;
MPEG-TS por HTTP;
stream fMP4;
MSS;
VOD.

Diagnóstico¶

Contadores del streamer (Prometheus) por perfil:

Contador	Qué cuenta
`device_profile_checks_total{profile}`	masters y manifiestos en los que el streamer comprobó las condiciones del perfil
`device_profile_input_absent_total{profile}`	de ellos, solicitudes sin ningún encabezado ni parámetro nombrado en las condiciones
`device_profile_selected_total{profile, by}`	el perfil se eligió: `by="match"` por condiciones, `by="path"` por URL
`device_profile_noop_total{profile}`	elegido, pero no quitó nada
`device_profile_empty_total{profile}`	respuestas 400 de resultado vacío
`device_profile_undescribed_total{profile}`	playlists de archivo bajo el perfil en los que la grabación no tiene descripción de pistas y el filtrado no se aplicó
`device_profile_unknown_total`	solicitudes bajo un perfil que el streamer no conoce
`device_profile_track_numbers_total{covered}`	solicitudes con selección de pistas por número de Flussonic; `covered="false"`: ningún perfil las cubrió

Cómo leerlos:

checks e input_absent crecen a la vez y selected no. El encabezado o el parámetro no llega al streamer: lo recorta una CDN, un proxy o una redirección. Elija el perfil con la URL p/<perfil>/.
checks no crece. El perfil nunca se alcanza: antes se elige otro perfil, o la solicitud queda fuera de sus modos y streams.
selected crece junto con noop. El perfil se elige, pero el stream no tiene pistas a las que se apliquen sus límites.

Perfiles por la API¶

El documento de perfiles es GET y PATCH (JSON Merge Patch) en /central/api-v4/device_profiles. PATCH cambia solo los perfiles nombrados, y null bajo un nombre elimina el perfil; envíe If-Match con el ETag de la lectura para que una edición paralela vuelva como 412 en lugar de sobrescribirse:

curl -X PATCH http://<dirección de central>/central/api-v4/device_profiles \
  -H 'Content-Type: application/merge-patch+json' -H 'If-Match: "<etag>"' \
  -d '{
    "roku-4800x": {
      "priority": 10,
      "match": {"headers": {"x-cdn-dev-model": "4800x"}},
      "video": {"fps": [{"max": 30}]}
    },
    "arris": {
      "priority": 20,
      "match": {"query": {"device_profile": ["arris", "arris-4205"]}},
      "video": {"codecs": ["h264"]}
    },
    "webos": {
      "priority": 30,
      "match": {"user_agent": "Web0S"},
      "text": {"exclude_all": true}
    }
  }'

Un error en el documento vuelve como 422 con la ruta al campo, la misma que resalta la consola. Un streamer entrega los perfiles que aplicó en GET /streamer/api-v4/device_profiles.