Media transcription and direct text output

Core workflow

Process requests in this order:

1. Verify that the input is a supported local file or a public single-item media link.
2. Prefer captions or an official transcript already exposed by the page. After obtaining usable text, do not download or transcribe the media again.
3. Before downloading a managed tool or sending media off-device, disclose the exact action and obtain the user's explicit approval for that action.
4. Only when no usable text exists and the user approves remote processing, obtain the required VoiceFlow token and run ASR.
5. Return the script's text verbatim. Do not proactively proofread, correct, rewrite, summarize, translate, or add content absent from the source.

Require explicit approval

Do not treat a transcription request by itself as approval to modify the host or upload media. Consent flags apply only to the current command and must never be persisted or added speculatively.

If the script reports that yt-dlp is unavailable, show the user the reported version, official source, and cache directory. Ask whether it may download and cache that pinned, SHA-256-verified release. Only after an affirmative response, rerun the command with --allow-tool-download. Never install FFmpeg or another system dependency without separately explaining the change and obtaining the user's explicit approval.

Before adding --allow-remote-asr, tell the user that:

• the local media or downloaded/extracted audio, plus its filename, content type, and size, will be sent over HTTPS to the VoiceFlow API at https://asr.audioflow123.com and to a provider-issued signed HTTPS object storage URL;
• the VoiceFlow token is sent only to the API, not to the signed storage URL;
• VoiceFlow deletes the uploaded media as soon as transcription reaches a terminal state, before returning that terminal result. The deletion is idempotent and best-effort; if it is interrupted, the private storage bucket's mandatory lifecycle policy removes the object within 2–3 days; and
• no media has been uploaded yet.

Ask a direct yes-or-no question. Add --allow-remote-asr only after the user explicitly agrees. If the user declines or does not answer, stop without upload.

Obtain a VoiceFlow token

A public media page may expose captions or an official transcript. Run the transcription command first for a URL and authorize only if the script reports that ASR needs a credential. Caption extraction does not require --allow-remote-asr.

Resolve the directory containing this SKILL.md as {baseDir}. Before transcribing a local file, inspect the connection:

node "{baseDir}/scripts/auth.mjs" status

When the status is not_connected, start browser authorization:

node "{baseDir}/scripts/auth.mjs" begin

Show verification_uri_complete and user_code to the user unchanged. Only the user may sign in, register, and approve in the browser. Never request or handle their email password or payment credentials. After the user confirms approval, run:

node "{baseDir}/scripts/auth.mjs" wait

The complete vf_stt_ token is generated locally. The script submits only its digest and stores the approved token in the operating-system user configuration directory; Unix credential files use mode 0600. An existing VOICEFLOW_TOKEN takes precedence and must not be persisted. Never echo or log a token, put it in command arguments, or write it to the repository.

For an invalid token, run begin again. To revoke an old key or add prepaid credit, direct the user to the VoiceFlow dashboard.

Accept input

• Accept local FLAC, M4A, MP3, MP4, MPEG, OGG, WAV, and WebM files up to 512 MiB.
• For local MP4, MPEG, and WebM files, the script extracts audio locally with FFmpeg and submits it as MP3 after remote-ASR approval. If FFmpeg is unavailable, explain the required installation and ask for explicit approval before running any package-manager or system-modifying command.
• Accept HTTPS public single-video pages, public podcast episode pages, and official share links.
• Reject channels, profiles, podcast homepages, search results, playlists, live streams, protected media, private or paid content, media that requires login, and non-public or network-local URLs.
• If a page contains multiple media items, ask the user for one specific video or podcast episode link.

Common public media sites

Submit a directly accessible HTTPS page for one public video or podcast episode, or its official share link. Common examples include:

Platform	Accepted URL examples
Xiaoyuzhou Podcasts	xiaoyuzhoufm.com/episode/...
YouTube	youtube.com/watch?v=..., youtu.be/...
Bilibili	bilibili.com/video/BV..., b23.tv/...
Youku, iQIYI	youku.com/v_show/..., iqiyi.com/v_...
Douyin, TikTok	douyin.com/video/..., tiktok.com/...
Xigua Video, Xiaohongshu	ixigua.com/..., xiaohongshu.com/explore/...
Vimeo, Dailymotion	vimeo.com/..., dailymotion.com/video/...
X / Twitter	x.com/.../status/..., twitter.com/.../status/...
Instagram	instagram.com/reel/..., instagram.com/p/...
Facebook	facebook.com/watch/?v=..., a public video or Reel page

Also try public single-item media pages from news, course, and other media sites. Site behavior can change, so support depends on whether the specific page can be resolved at the time of the request.

Xiaoyuzhou episodes

For Xiaoyuzhou, accept only a public episode URL matching https://www.xiaoyuzhoufm.com/episode/<24-character-id> or the equivalent URL without www. Reject podcast homepages, lists, live streams, and private or paid episodes.

Xiaoyuzhou always requires public episode audio retrieval and VoiceFlow ASR. Complete the external-processing disclosure and obtain approval before running the URL command with --allow-remote-asr. Do not add the removed --xiaoyuzhou-mode option.

Never request a phone number, CAPTCHA result, SMS code, or Xiaoyuzhou account credential. Do not call Xiaoyuzhou login, SMS verification, or official transcript interfaces.

Transcribe

After explicit remote-ASR approval, use an absolute path for a local attachment:

node "{baseDir}/scripts/transcribe.mjs" --file "/absolute/path/audio.wav" --allow-remote-asr

Use the complete URL for public media:

node "{baseDir}/scripts/transcribe.mjs" --url "https://example.com/watch/id"

The first URL run may return captions without any media upload. If it reports that remote ASR is required, complete the disclosure and obtain approval before rerunning with --allow-remote-asr. Add --allow-tool-download only after the separate managed-tool approval described above.

Add --language <code> only when the user specifies the source language or it is otherwise known, for example --language en or --language zh. Except for Xiaoyuzhou, the script may return existing page captions without invoking ASR. Treat all returned text as an immutable raw transcript for the rest of the workflow.

Do not send client hot words to the remote VoiceFlow path. They may contain private names, and the backend does not support prompts. Only an explicitly approved offline ASR tool may consume locally generated client hot words.

Extract text and reply directly

On success, standard output contains the final text or JSON. Local media produces a speech transcript; a public URL produces existing page text or an ASR result. Read only the text from standard output. If the output is JSON, extract only its transcript text value. Never mix progress, diagnostics, or internal state from standard error into the result.

Send the extracted text verbatim as the final response. Do not proactively proofread, correct, polish, summarize, translate, generate an extra file, or add unrelated explanation. Do not alter the content except to remove the single trailing newline added to terminate command output.

Treat empty standard output as no text obtained and follow failure handling. Do not repeat transcription after text has been obtained successfully.

Failure handling

Briefly report that the media cannot currently be processed. For a URL failure, ask for a public single-video or podcast episode link, or a local upload. If text has already been obtained, deliver it instead of discarding it because of an unrelated later state or message.

Consent-required messages are not processing failures. Present the disclosure and ask for approval, then continue only after an explicit affirmative response.

Version

Version 1.6.1: document VoiceFlow's immediate post-transcription media deletion and bounded private-storage lifecycle fallback.