Formatar capítulos de áudio para apps

Aplicativos de podcast compatíveis com capítulos Podcasting 2.0 esperam um pequeno arquivo JSON ligado ao item RSS do episódio, e não marcadores embutidos no MP3. Esta capacidade recebe as linhas de capítulos ordenadas—título mais tempo de início em segundos, com imagem e URL opcionais por capítulo—e emite o objeto chapters versionado padrão mais uma string json_text formatada que você pode hospedar e referenciar com a tag podcast:chapters. Se os tempos de início não forem estritamente crescentes, a tarefa falha com invalid_input para que marcadores incorretos não cheguem ao feed.

Como é o JSON de capítulos Podcasting 2.0

Esse arquivo é um objeto JSON cujas chaves obrigatórias são version (comumente 1.2.0) e chapters, um array de marcadores ordenados por startTime ascendente. Campos opcionais no nível do arquivo como author, title, podcastName e description ajudam players web e arquivos sem mudar como os apps saltam pelo áudio. Este exportador mapeia a entrada em linhas—start_time e title em cada capítulo, img e url opcionais—para essa forma camelCase, para que você não edite chaves manualmente nem esqueça a string de versão. Hospede o json_text resultante em uma URL HTTPS estável e adicione podcast:chapters com type application/json+chapters no item.

Contrato de entrada, forma da resposta e regras de validação

Chaves de saída opcionais são omitidas por completo em vez de definidas como null. Envie por POST um corpo JSON com um array chapters obrigatório de pelo menos um objeto. Cada objeto deve incluir title como string não vazia e start_time como número finito não negativo em segundos (aliases como startTime são aceitos em cada linha). Campos opcionais por capítulo são img e url como strings não vazias, toc como booleano (false marca um capítulo silencioso; true é o padrão e é omitido na exportação), e end_time como número não negativo não inferior ao início daquele capítulo. Strings opcionais no nível do arquivo—version (padrão 1.2.0), episode_title, author, podcast_name e description—são copiadas para o objeto chapters quando presentes. Em caso de sucesso o corpo retorna version, chapter_count, chapters como o array Podcasting 2.0 com chaves startTime, json_text como o arquivo formatado pronto para upload, mime_type em application/json+chapters, e quaisquer metadados de episódio fornecidos sob author, title, podcast_name e description. Falhas de validação lançam invalid_input e não são cobradas: chapters ausente, title vazio, tempos negativos ou não finitos, fim antes do início, mais de quinhentas linhas, ou tempos de início que não são estritamente crescentes. Exemplo: três linhas em zero, cento e vinte e mil e oitocentos segundos com imagem e link no capítulo do meio produzem um array chapters de três entradas e uma string json_text que coincide em estrutura com os exemplos públicos de Podcasting 2.0.

Onde um exportador determinístico de capítulos vale a pena

Ferramentas de transcrição ou de sugestão de capítulos que emitem pares de título e segundos podem encaminhar o resultado aqui para obter o formato orientado ao app sem embutir o conhecimento de Podcasting 2.0 em cada cliente. Validação com falha não consome saldo. Combine este exportador com produtos separados de geração de capítulos por ASR quando precisar inventar marcas a partir do áudio; use este caminho quando já conhecer os marcadores e só precisar de uma exportação conforme o padrão. Produtores independentes que finalizam um episódio em um DAW já têm carimbos de tempo em uma planilha ou nas notas do programa; precisam de um arquivo JSON correto sem aprender o namespace por tentativa e erro em cada app. Como a implementação é pure parse de nível A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo e sem rede de saída. Mantenha os títulos de capítulo curtos o bastante para UIs de índice em mobile, prefira URLs HTTPS absolutas para img e url, e execute o formatador de novo após cada edição para que a ordem estritamente crescente continue sendo aplicada.