Transforme uma gravação de música em uma letra conferida com HeartMuLa

O HeartMuLa Transcribe transforma uma gravação de música em um rascunho de texto por $0.05 por solicitação, tanto que a faixa dure vinte segundos quanto seis minutos. Envie uma URL de áudio direta, leia a letra em data.output.text e depois confira os trechos repetidos e as palavras incertas contra essa mesma gravação. A tarefa não devolve tempos por linha, rótulos de cantor nem notas de confiança, então uma letra conferida e um arquivo de legendas sincronizadas são dois trabalhos separados.

O que a tarefa aceita e devolve

A página do HeartMuLa Transcribe lista uma entrada, audio_url: um MP3 ou WAV de até 90 MB. Não há campo de prompt, de tamanho de modelo nem de marcação de tempo, e também não há ajuste de idioma: o modelo identifica o idioma pelo áudio, de modo que a letra em outros idiomas funciona do mesmo jeito. Ele foi feito para voz sobre música; para uma entrevista ou um podcast, um modelo de fala geral como Grok STT encaixa melhor. É um modelo sem censura: a letra explícita volta como é cantada, sem mascaramento nem recusa, e você continua responsável pelos direitos do áudio.

O reconhecedor de letras aberto do HeartMuLa, HeartTranscriptor, é baseado no Whisper e foi treinado em faixas vocais separadas; seus autores recomendam separar a voz primeiro. A solicitação hospedada não tem interruptor de separação. Se uma gravação tiver uma mixagem de acompanhamento pesada, você pode rodar uma ferramenta de separação como Demucs por conta própria e enviar a faixa vocal como segunda solicitação. Trate essa faixa como um experimento: compare qualquer palavra que ela mudar com a mixagem original, porque a separação pode introduzir artefatos, e uma voz de estúdio não consegue decidir uma palavra em outra performance. Vozes sussurradas ou gritadas e arquivos de bitrate muito baixo voltam piores; envie o MP3 ou WAV de melhor qualidade que você tiver.

Teste primeiro no Playground

Abra a página do HeartMuLa Transcribe e fique na aba Playground.

1. Em Input audio, pressione Choose a file (MP3 ou WAV, até 90 MB) ou mude para Asset URL e pressione Add URL para um arquivo hospedado em outro lugar. Esse é o único campo.
2. Confira a estimativa de preço: $0.05, qualquer que seja a duração.
3. Entre na conta e execute. O texto da letra aparece no painel Output, com uma visão JSON ao lado da pré-visualização.

A URL precisa devolver o próprio arquivo de áudio, não um player, uma página de compartilhamento ou uma página de login, ou a tarefa falha como recurso inválido. Guarde sua própria cópia da versão exata que você envia, para que a transcrição continue ligada a essa performance. Teste aqui a sua faixa mais difícil antes de enfileirar um lote.

Ou chame pelo código

Instale o SDK de Python (pip install spicyapi, Python 3.11+), defina SPICY_API_KEY com a sua chave do lado do servidor e execute:

from pathlib import Path
import uuid

from spicyapi import SpicyClient

client = SpicyClient()  # reads SPICY_API_KEY from the environment

song = client.upload_file("./authorized-original-song.wav")  # uploads are kept for one day
task = client.create_task(
    model="heartmula/transcribe/speech-to-text",
    input_data={"audio_url": song["uri"]},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

# The lyrics are text on the task, not a file; save them now, task content is not permanent
Path("lyrics-draft.txt").write_text(final["output"]["text"])

Uploads, espera, erros e novas tentativas estão na referência do SDK de Python, e o guia de tarefas cobre o ciclo de vida da tarefa e os callbacks. Uma faixa instrumental devolve pouco ou nada e mesmo assim é cobrada como uma execução bem-sucedida, então elimine faixas sem voz antes de enfileirar um lote. Uma tarefa concluída atesta a conclusão, não a precisão.

Ou deixe um Agent rodar

Se um assistente deve transcrever uma pasta de músicas para você, entregue a ele a CLI ou o servidor MCP. Os dois mostram o preço e pedem confirmação antes de uma chamada paga. O Skill acrescenta instruções a qualquer um dos dois.

• CLI. spicyapi roda uma tarefa a partir de um terminal (npx @spicyapi/cli funciona sem instalar):

``bash spicyapi files upload ./song.wav # prints a spicy:// URI spicyapi tasks create --model heartmula/transcribe/speech-to-text \ --input-json '{"audio_url": "spicy://YOUR-UPLOAD-URI"}' --wait ``

• Servidor MCP. Adicione o servidor MCP ao seu assistente e então pergunte: "Transcreva a letra de ./song.wav com o HeartMuLa Transcribe." Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para sua confirmação de preço) e depois spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que ensina um assistente de programação a ler o esquema vigente e a reutilizar chaves de idempotência. Ele não roda tarefas sozinho, então use-o com a CLI ou com o MCP.

Confira a cobertura antes da pontuação

Reproduza a fonte uma vez e anote sua estrutura: verso, refrão, ponte e final (outro). Compare essa sequência com o rascunho. Uma transcrição fluida pode fundir dois refrões em um, e arrumar a pontuação não devolve a performance que falta. Modelos no estilo Whisper também podem repetir uma linha, omitir uma passagem curta ou produzir palavras sobre um "ooh" longo ou um zumbido, então escute em qualquer ponto em que o texto pareça em loop ou confiante demais.

Não apague palavras repetidas automaticamente. Elas podem ser um eco cantado, uma frase principal repetida ou um erro de reconhecimento; rebobine esse ponto e decida. Guarde um rascunho sem alterações para que uma mudança do editor nunca seja atribuída ao modelo.

Mantenha cada repetição como ela é cantada. Pegue uma música fictícia cujo primeiro refrão diz "Leave the lamp beside the window" e cujo último diz "Leave the lamp beneath the window." As duas cabem na melodia. A transcrição deve manter a mudança realmente cantada, em vez de copiar o primeiro refrão sobre o segundo.

Resolva as palavras que mudam o sentido

Priorize negações, nomes, números e palavras curtas que invertem uma linha. "Do not close the garden gate" e "Do close the garden gate" são lidos sem problema e significam o oposto uma da outra. Rebobine com alguns segundos de contexto dos dois lados, porque uma consoante isolada é mais difícil de ouvir do que a frase inteira.

Se o áudio continuar ambíguo, pergunte a quem canta ou guarde uma nota privada de incerteza. Não resolva uma palavra disputada por votação majoritária entre transcrições repetidas: palpites idênticos não são evidência independente. Para canto em camadas, decida se a folha cobre apenas a voz principal ou todas as linhas de acompanhamento audíveis, e adicione rótulos de papel apenas a partir da sua própria escuta ou das suas notas de produção.

Adicione legendas depois de conferir as palavras

A tarefa não devolve marcações de tempo. Abra a montagem final de áudio ou vídeo em um editor de legendas, adicione um cue para cada frase cantada e defina os horários de início e fim em relação a essa performance. Confira a primeira entrada da voz, cada refrão repetido e a última linha. Distribuir as linhas uniformemente pela duração falha, porque as pausas instrumentais e as sílabas sustentadas são irregulares.

Realinhe depois de qualquer edição no áudio. Mantenha o texto no idioma original separado de qualquer tradução: a tarefa não tem campo de tradução, e uma adaptação cantável muda as palavras e o ritmo.

Calcule o orçamento por gravação

O custo é o número de solicitações multiplicado por $0.05: dois arranjos vocais custam $0.10, adicionar uma solicitação de faixa vocal para cada um leva a $0.20, e vinte e quatro gravações custam $1.20 antes das novas tentativas. Como a duração nunca entra no preço, uma pasta de clipes curtos sai relativamente cara por minuto. Envie uma música por solicitação: várias músicas concatenadas em um único arquivo voltam como um bloco contínuo de texto sem fronteiras, e sem marcações para reconstruí-las.