vivadicta transcribe flow

Use this skill to turn an audio file or a YouTube URL into a searchable transcription in the user's VivaDicta history. Covers input-shape detection, blocking vs --async, progress output, and recovery paths.

Preconditions

• VivaDicta.app installed at /Applications/VivaDicta.app and running (writes require the UI).
• User has a transcription model configured (Whisper local, Parakeet local, or a cloud provider with API key in Keychain).
• For YouTube URLs, the app's YouTube transcription is enabled (one of: captions → Apify → yt-dlp → Whisper).

Pick the source and invocation

# Local file, blocking (default) - waits until done, prints the final transcription summary
vivadicta transcribe ~/Downloads/meeting.m4a

# YouTube URL, blocking
vivadicta transcribe "https://youtu.be/dQw4w9WgXcQ"

# Either source, async - returns the job UUID immediately
vivadicta transcribe ~/Downloads/meeting.m4a --async

Input auto-routes:

Ambiguous or nonexistent paths exit 2 with a clear message.

Blocking vs async

Blocking (default): the command waits up to VIVADICTATIMEOUTSECONDS (default 600) polling every 2 s, then prints the full transcription summary on stdout (same shape as vivadicta get). Progress phase lines stream to stderr: [vivadicta] downloading captions… / [vivadicta] transcribing (parakeet)… / [vivadicta] enhancing (claude)….

Prefer blocking when:

• The next step in the user's request needs the transcript (rewrite, grep, summarize).
• The audio is short (<1 min) or the transcription model is local.

Async (--async): returns a job UUID immediately. Poll with vivadicta job <uuid> when you want status.

JOB=$(vivadicta transcribe ~/Downloads/long-meeting.m4a --async --output json | jq -r '.job')
# ... do other work ...
vivadicta job "$JOB"          # one-shot check

Prefer async when:

• Audio is long and the user doesn't need the transcript right away.
• You want to dispatch multiple transcriptions in parallel (the UI app serialises by kind; one URL + one file can run concurrently).

Progress output in JSON mode

When the user asked for JSON (--output json or pipe), blocking-mode progress becomes newline-delimited JSON events on stderr (stdout stays clean for the final payload):

{"elapsed_ms":0,"event":"phase","message":"Starting transcribe_url…"}
{"elapsed_ms":4120,"event":"phase","message":"Downloading captions"}
{"elapsed_ms":12004,"event":"phase","message":"Enhancing (claude-sonnet-4-6)"}
{"elapsed_ms":18500,"event":"done","message":"Transcription saved."}

Scripts can jq stderr for live progress.

Typical end-to-end flow

# 1. Transcribe and save
vivadicta transcribe "https://youtu.be/dQw4w9WgXcQ"

# 2. If you want to further process, the saved record is now the "latest" - grab its UUID
UUID=$(vivadicta recent 1 --output json | jq -r '.transcriptions[0].ref')

# 3. Rewrite with a preset (see vivadicta-search-and-rewrite)
vivadicta rewrite "$UUID" --preset summary

# 4. Export to Obsidian (see vivadicta-vault-export)
vivadicta get "$UUID" --output markdown > ~/vault/transcripts/$(date +%F).md

Dry-run

Before hitting the UDS, preview the resolved plan:

vivadicta transcribe ~/Downloads/meeting.m4a --dry-run
# Action  : transcribe (dry-run)
# Route   : transcribe_file
# Resolved: /Users/you/Downloads/meeting.m4a
# Async   : no (blocking)

Works with the UI app stopped (no UDS call). Useful for verifying the user's input was parsed correctly before running a long job.

Error recovery

Guardrails

• Never pass --async when you're immediately consuming the transcript - the UUID alone is useless for the next step.
• When the user asks "transcribe X", prefer the blocking path so the transcript text is present in the agent's response.
• Don't try to transcribe a format the app doesn't handle (proprietary containers). Stick to audio formats afinfo can introspect; the app supports the usual m4a/mp3/wav/flac/aac list.
• If a YouTube URL needs cookies (private video), the CLI can't pass them - the UI app's cookie store is used. Ask the user to open the URL in their default browser first if the job fails with an auth-ish error.
• Progress phases are hints, not SLAs. Don't show exact timestamps to the user unless they asked.

See vivadicta-cli-usage for exit-code details and TTY behavior.