Formatear capítulos de audio para apps

Las aplicaciones de podcast compatibles con capítulos Podcasting 2.0 esperan un pequeño archivo JSON enlazado desde el ítem RSS del episodio, no marcadores embebidos en el MP3. Esta capacidad recibe sus filas de capítulos ordenadas—título más tiempo de inicio en segundos, con imagen y URL opcionales por capítulo—y emite el objeto chapters versionado estándar más una cadena json_text con formato legible que puede hospedar y referenciar con la etiqueta podcast:chapters. Si los tiempos de inicio no son estrictamente crecientes, la tarea falla con invalid_input para que marcadores incorrectos no lleguen al feed.

Cómo es el JSON de capítulos Podcasting 2.0

Ese archivo es un objeto JSON cuyas claves obligatorias son version (habitualmente 1.2.0) y chapters, un array de marcadores ordenados por startTime ascendente. Campos opcionales a nivel de archivo como author, title, podcastName y description ayudan a reproductores web y archivos sin cambiar cómo las apps saltan por el audio. Este exportador mapea su entrada por filas—start_time y title en cada capítulo, img y url opcionales—a esa forma camelCase para que no edite llaves a mano ni olvide la cadena de versión. Hospede el json_text resultante en una URL HTTPS estable y añada podcast:chapters con type application/json+chapters en el ítem.

Contrato de entrada, forma de respuesta y reglas de validación

Las claves de salida opcionales se omiten por completo en lugar de ponerse a null. Envíe por POST un cuerpo JSON con un array chapters obligatorio de al menos un objeto. Cada objeto debe incluir title como cadena no vacía y start_time como número finito no negativo en segundos (se aceptan alias como startTime en cada fila). Los campos opcionales por capítulo son img y url como cadenas no vacías, toc como booleano (false marca un capítulo silencioso; true es el valor por defecto y se omite en la exportación), y end_time como número no negativo no inferior al inicio de ese capítulo. Las cadenas opcionales a nivel de archivo—version (predeterminado 1.2.0), episode_title, author, podcast_name y description—se copian al objeto chapters cuando están presentes. En caso de éxito el cuerpo devuelve version, chapter_count, chapters como el array Podcasting 2.0 con claves startTime, json_text como el archivo con formato listo para subir, mime_type en application/json+chapters, y los metadatos de episodio aportados bajo author, title, podcast_name y description. Los fallos de validación lanzan invalid_input y no se facturan: chapters ausente, title vacío, tiempos negativos o no finitos, fin anterior al inicio, más de quinientas filas, o tiempos de inicio que no son estrictamente crecientes. Ejemplo: tres filas en cero, ciento veinte y mil ochocientos segundos con imagen y enlace en el capítulo del medio producen un array chapters de tres entradas y una cadena json_text que coincide en estructura con los ejemplos públicos de Podcasting 2.0.

Dónde un exportador determinista de capítulos aporta valor

Las herramientas de transcripción o de sugerencia de capítulos que emiten pares de título y segundos pueden canalizar su resultado aquí para obtener el formato orientado a la app sin incrustar el conocimiento de Podcasting 2.0 en cada cliente. La validación fallida no consume saldo. Combine este exportador con productos aparte de generación de capítulos por ASR cuando necesite inventar marcas a partir del audio; use esta ruta cuando ya conozca los marcadores y solo precise una exportación conforme al estándar. Los productores independientes que terminan un episodio en un DAW ya tienen marcas de tiempo en una hoja de cálculo o en las notas del programa; necesitan un archivo JSON correcto sin aprender el espacio de nombres a prueba y error en cada app. Como la implementación es pure parse de nivel A, cada llamada exitosa cuesta el precio base publicado $0.002 sin tokens de modelo y sin red saliente. Mantenga los títulos de capítulo lo bastante cortos para las interfaces de índice en móvil, prefiera URL HTTPS absolutas para img y url, y vuelva a ejecutar el formateador tras cada edición para que el orden estrictamente creciente siga aplicándose.