Turn a Song Recording into a Checked Lyric Sheet with HeartMuLa

HeartMuLa Transcribe turns a song recording into a text draft for $0.05 per request, whether the track is twenty seconds or six minutes. Send one direct audio URL, read the lyrics from data.output.text, then check repeated sections and uncertain words against that same recording. The task returns no line timings, singer labels or confidence scores, so a checked lyric sheet and a synchronized caption file are two separate jobs.

What the task takes and returns

The HeartMuLa Transcribe page lists one input, audio_url: an MP3 or WAV up to 90 MB. There is no prompt, model-size or timestamp field, and no language setting either: the model picks the language up from the audio, so non-English lyrics work the same way. It is built for vocals over music; for an interview or podcast, a general speech model such as Grok STT is the better fit. It is an uncensored model: explicit lyrics come back as sung, with no masking or refusal, and you remain responsible for the rights to the audio.

HeartMuLa's open lyric recogniser, HeartTranscriptor, is Whisper-based and trained on separated vocal tracks, and its authors recommend separating vocals first. The hosted request has no separation switch. If a recording has a heavy backing mix, you can run a separation tool such as Demucs yourself and submit the vocal stem as a second request. Treat the stem as an experiment: compare any word it changes with the original mix, because separation can introduce artifacts, and a studio vocal cannot settle a word in a different performance. Whispered or screamed vocals and very low-bitrate files come back worse; submit the best-quality MP3/WAV you have.

Try it in the Playground first

Open the HeartMuLa Transcribe page and stay on the Playground tab.

1. Under Input audio, press Choose a file (MP3 or WAV, up to 90 MB), or switch to Asset URL and press Add URL for a file hosted elsewhere. That is the only field.
2. Check the price estimate: $0.05, whatever the length.
3. Log in and run. The lyric text appears in the Output panel, with a JSON view next to the preview.

The URL must return the audio file itself, not a player, share page or login page, or the task fails as an invalid asset. Keep your own copy of the exact version you submit, so the transcript stays tied to that performance. Run your hardest track here before you queue a batch.

Then call it from code

Install the Python SDK (pip install spicyapi, Python 3.11+), set SPICY_API_KEY to your server-side key, and run:

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, waiting, errors and retries are in the Python SDK reference, and the task guide covers the task lifecycle and callbacks. An instrumental track returns little or nothing and is still billed as a successful run, so screen out tracks with no vocal before queuing a batch. A finished task establishes completion, not accuracy.

Or let an Agent run it

If an assistant should transcribe a folder of songs for you, give it the CLI or the MCP server. Both show the price and ask you to confirm before a paid call. The Skill adds instructions on top of either.

• CLI. spicyapi runs one task from a terminal (npx @spicyapi/cli works without installing):

``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 ``

• MCP server. Add the MCP server to your assistant, then ask: "Transcribe the lyrics in ./song.wav with HeartMuLa Transcribe." It calls spicyapi_upload_file, then spicyapi_task_create (which stops for your price confirmation), then 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 installs the Agent Skill, which teaches a coding assistant to read the live schema and reuse idempotency keys. It cannot run tasks by itself, so use it with the CLI or MCP.

Check coverage before punctuation

Play the source once and write down its structure: verse, chorus, bridge, outro. Compare that sequence with the draft. A fluent transcript can fold two choruses into one, and tidying punctuation will not restore the missing performance. Whisper-style models can also repeat a line, drop a short passage, or produce words over a long "ooh" or hum, so listen at any spot where the text looks looped or oddly confident.

Do not delete repeated words automatically. They may be a sung echo, a repeated lead phrase or a recognition error; replay the location and decide. Keep an untouched draft so an editor's change is never attributed to the model.

Keep each repetition as sung. Take an invented song whose first chorus says "Leave the lamp beside the window" and whose last says "Leave the lamp beneath the window." Both fit the melody. The transcript should keep the change actually sung, rather than copy the first chorus over the second.

Resolve the words that change meaning

Prioritize negations, names, numbers and small words that flip a line. "Do not close the garden gate" and "Do close the garden gate" both read fine and mean opposite things. Replay with several seconds of context on both sides, because one isolated consonant is harder to hear than the full phrase.

If the audio stays ambiguous, ask the performer or keep a private uncertainty note. Do not settle a disputed word by majority vote across repeated transcriptions: identical guesses are not independent evidence. For layered singing, decide whether the sheet covers the lead only or every audible backing line, and add role labels only from your own listening or production notes.

Add captions after the words are checked

The task returns no timestamps. Open the final audio or video edit in a subtitle editor, add a cue for each sung phrase and set start and end times against that performance. Check the first vocal entrance, each repeated chorus and the last line. Spreading lines evenly over the duration fails because instrumental breaks and held syllables are uneven.

Re-align after any edit to the audio. Keep the original-language text separate from any translation: the task has no translation field, and a singable adaptation changes wording and rhythm.

Budget by recording

Cost is requests times $0.05: two vocal arrangements cost $0.10, adding a vocal-stem request for each takes it to $0.20, and twenty-four recordings cost $1.20 before retries. Because duration never enters the price, a folder of short clips is relatively expensive per minute. Submit one song per request: several songs concatenated into one file come back as one unbroken block of text with no boundaries, and no timings to rebuild them.