1.5.20: Take the speech-to-text audio from a format with sound when a platform has no audio-only format

[samson-art]

Closes #63

What and why

Speech-to-text downloads the audio with -f bestaudio[abr<=192]/bestaudio. TikTok offers no audio-only format: each format holds both video and sound. So yt-dlp stopped with Requested format is not available, and the caller got "no subtitles". Since 1.5.13 every get_transcript call on TikTok without lang goes to speech-to-text, so this was the usual answer for TikTok. Over the last 7 days it was the most common TikTok error of get_transcript.

The default of YT_DLP_AUDIO_FORMAT now ends with /best*[acodec!=none]. When a platform has no audio-only format, yt-dlp takes the best format that has sound, and --extract-audio keeps only the sound. Platforms with an audio-only format match the first part of the selector, so they get the same format as before.

Plan

Files that change

• src/youtube.ts: the default selector in downloadAudio.
• src/youtube.test.ts: a new test for the default -f value. The old default test now expects the new value.
• .env.example, CHANGELOG.md: the new default. The README env table does not list this variable.

Order of work

1. Write the test for the -f value and see it fail.
2. Change the default.
3. Run the gate and the mutation drill.
4. Check the selector by hand on a real TikTok video.

Risks

• A deployment that sets YT_DLP_AUDIO_FORMAT to the old default keeps the bug. The CHANGELOG says so.
• best* can be a larger download than an audio-only format. It is used only where no audio-only format exists. WHISPER_MAX_DURATION_SECONDS, YT_DLP_MAX_FILESIZE and YT_DLP_AUDIO_TIMEOUT still apply.
• This is not the caption path. The download is still one run through execFileAsync.

Verified

• Before the fix: the new test failed with Expected: "bestaudio[abr<=192]/bestaudio/best*[acodec!=none]", Received: "bestaudio[abr<=192]/bestaudio".
• make check-no-smoke: green, 17 suites, 488 tests.
• Mutation drill, 1 of 1: with the old selector back, falls back to a format with sound when the platform has no audio-only format (#63) and should pass format and audio-quality to yt-dlp and return path to audio file fail.
• By hand, one public TikTok video, yt-dlp 2026.03.13: the old selector gives Requested format is not available. The new selector picks a format with aac sound. A full run with --extract-audio --audio-format m4a gives an m4a file with one audio stream of 10.5 s.

Not verified

• A speech-to-text run on that audio. There is no Whisper service on my machine. Check after deploy (below).
• YouTube by hand. The first part of the selector is the same as before, so YouTube gets the same format.

Not in scope

• TikTok links that yt-dlp does not recognize (Unsupported URL).
• Listing TikTok tracks without lang.

After merge

• get_transcript on a public TikTok video with speech, without lang: returns text.
• In the logs, no new Requested format is not available lines from the audio download.
• get_transcript not_found errors on TikTok drop in the next weekly report.

🤖 Generated with Claude Code