Skip to content

n0an/vivadicta-cli-skills / skills/vivadicta-transcribe-flow

vivadicta-transcribe-flow

Verified

Transcribe a local audio file or YouTube URL end-to-end with vivadicta, handling blocking vs async, progress, and error recovery. Use when the user wants speech from an audio source saved into their VivaDicta history.

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:

Input shapeRoutes to
http:// / https:// prefixtranscribe_url (YouTube)
file:// prefixstrip scheme, treat as path
Absolute path (/...), ~/..., ./, ../, or a bare filename that resolves against CWDtranscribe_file
- (stdin)rejected (not supported in v1)

Ambiguous or nonexistent paths exit 2 with a clear message.

Blocking vs async

Blocking (default): the command waits up to VIVADICTA_TIMEOUT_SECONDS (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

ExitErrorWhat to do
5vivadicta_not_runningAsk the user to launch VivaDicta, then retry. Don't loop-retry - the UDS socket appears only after launch.
6daily_limit_reachedUser is on the free tier and hit today's AI-enhancement quota. Transcription still completes; enhancement is skipped. Suggest Pro at https://vivadicta.com/pro.
2invalid_argumentsUsually means the file doesn't exist or the URL scheme is wrong. Rerun with --dry-run to see how the input was parsed.
1internal_failure (on a blocking transcribe)The underlying job errored in the UI app (auth, network, model load). Check the error field in the JSON payload or stderr message. If the failure was transient (network) retry once; if it's consistent (auth) surface the message to the user.
timeoutTimed out after 600sJob is still running in the UI. Get the handle from the error message and switch to vivadicta job <uuid>. Don't spawn a duplicate.

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.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall