yichen-asr

Yichen Unified ASR

This is a unified routing layer, not a third ASR engine. Step ASR and Doubao ASR continue to serve as the underlying executors, while this Skill handles selection, health checks, failure convergence, and handoff.

Routing Rules

Requirement	Default Backend	Reason
Only full text, summary, or content analysis is needed	Step ASR	30-second slices; failed segments can be retried at 10/5 seconds
Finer timestamps or SRT subtitles are needed	Doubao ASR	Returns structured utterances and time information
Spoken pauses, filler word analysis, or automatic rough cutting is needed	Doubao ASR	Existing scripts include SRT and ffmpeg rough-cut chains
The user explicitly says "only use Step"	Step ASR	Must not fill in across providers
The user explicitly says "only use Doubao/Volcengine"	Doubao ASR	Must not fill in across providers

Automatic routing may only switch when no task has yet been submitted to any provider. If a request has already been uploaded, submitted, or has left a request ID, that task must be resumed or reported, and the same media must not be submitted to another provider, to avoid duplicate billing.

Use the offline router to confirm the selection:

python3 ~/.agents/skills/yichen-asr/scripts/route_asr.py \
  --provider auto --text-only

When subtitles are needed:

python3 ~/.agents/skills/yichen-asr/scripts/route_asr.py \
  --provider auto --need-timestamps --need-srt

Pre-execution Health Check

Run the read-only health check first; it only reports whether keys exist, does not display key contents, and does not call paid interfaces:

python3 ~/.agents/skills/yichen-asr/scripts/asr_doctor.py

In the health check, token_present only means that call credentials are configured on this machine; it does not mean the account has a balance. The ASR Token is not authorized to read Volcengine financial balance; balance and arrears status must be verified by logging into the Billing Center.

Step ASR

Executor:

python3 "$YICHEN_STEP_ASR_SCRIPT" \
  --input "/absolute/path/input.mp4" \
  --output-dir "/absolute/path/output" \
  --title "标题" \
  --resume

The public version does not include the Step ASR executor. Use YICHEN_STEP_ASR_SCRIPT to point to a compatible script you have installed and audited; it can also be installed as a peer step-asr/scripts/step_asr_transcribe.py. During execution, fully comply with the executor's SKILL.md. Do not delete failure markers, and do not silently fill Step failed segments with Doubao results.

Doubao ASR

Executor:

python3 ~/.agents/skills/yichen-volc-asr/scripts/transcribe.py \
  "/absolute/path/input.mp4" \
  --transcribe-only

When SRT and spoken-content rough cutting are needed, remove --transcribe-only; when only generating analysis and commands without executing editing, add --no-execute。

During execution, fully comply with ~/.agents/skills/yichen-volc-asr/SKILL.md. When the same media's .asr_pending.json is found, prioritize resuming the original task; unless the user explicitly authorizes it, do not use --force-new。

Doubao calls do not require web login every time. The public version does not include App ID, Token, or keychain names: trial and paid App IDs are provided via VOLC_ASR_TRIAL_APP_ID、VOLC_ASR_PAID_APP_ID respectively, and Tokens are provided via VOLC_ASR_TRIAL_TOKEN、VOLC_ASR_PAID_TOKEN respectively. The script directly submits local media to the fast version interface; for video, the audio track is first extracted in memory by ffmpeg.

Financial balance can only be viewed after logging into the Volcengine console:

Account overview and balance:https://console.volcengine.com/finance/account-overview/
Top-up instructions:https://www.volcengine.com/docs/3019/1176800?lang=zh

Failures and Fallback

User-specified provider: after a failure, report only that provider's error and recovery path; do not automatically switch providers.
Automatic routing and not yet submitted: if the default backend lacks a script, key, or required capability, another backend that meets the output requirements may be used instead, with explicit explanation.
Automatic routing and already submitted: do not resubmit across providers; prefer using the request ID, cache, or --resume to recover.
Doubao balance unknown: must not be described as "sufficient balance" or "insufficient balance." Only the billing center, invoices, or an explicit API arrears error can confirm it.
Exact SRT requirements must not be silently downgraded to Step's chunked Markdown because Doubao is unavailable; the capability difference should be explained.

Cost and Security

An explicit transcription request for a single file may be executed with the selected backend; for batch tasks or when significant paid quota may be incurred, first explain the number of files, total duration, and backend, then obtain user confirmation.
Do not output Cookies, Tokens, or API Keys; long-term credentials are stored only in the macOS Keychain and are not written into the Skill, scripts, logs, or memory.
Do not commit keys to the Skill, artifacts, logs, or memory files.
Do not automatically top up, purchase resource packs, or enable postpaid billing.
Do not overwrite existing artifacts. Temporary files must not be deleted automatically; any cleanup requires explicit user permission and may only move them to the Trash.

Handoff

Hand off at least the following to the upper-level research workflow:

{
  "provider": "step|doubao",
  "mode": "text|timestamps|srt|rough_cut",
  "input": "/absolute/path/input",
  "outputs": [],
  "request_id": null,
  "billing_status": "unknown|verified_ok|verified_insufficient",
  "errors": []
}

This Skill is the transcription sub-route of $yichen-web-research . The research main entry point decides when transcription is needed; this Skill is only responsible for ASR of existing local audio and video, and is not responsible for search, download, or archiving.