@youka/cli

Official command-line client for the Youka REST API.

Use this package to create karaoke videos from your terminal: upload audio or video, sync or transcribe lyrics, create a karaoke project, render the final video, and download the MP4.

Install

npm install -g @youka/cli

API key

Create an API key at online.youka.io/account under API keys.

Log in once:

youka login "yk_..."

Or keep the key in your environment:

export YOUKA_API_KEY="yk_..."

Inspect which account, key source, and API URL are active:

youka whoami --json

Create a karaoke video

Create a project from a local song, sync your lyrics, export the karaoke video, and download the MP4:

youka project create ./song.mp3 \
  --title "Artist - Song" \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --sync-model audioshake-alignment \
  --split-model mdx23c \
  --wait \
  --json

Then export the finished project:

youka export create proj_123 \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --json

Or do the whole flow in one command:

youka project create ./song.mp3 \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --download \
  --output ./karaoke.mp4 \
  --json

Transcribe lyrics automatically

Use transcription when you do not already have lyrics text:

youka project create ./song.mp3 \
  --mode transcribe \
  --download \
  --output ./karaoke.mp4 \
  --json

Use a hosted media URL

youka project create https://example.com/song.mp4 \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --download \
  --output ./karaoke.mp4 \
  --json

Install local helper binaries when needed for URL downloads and local rendering:

youka deps status --json
youka deps ensure --for all --json
youka deps ensure --for render --update --json
youka deps path ffmpeg

Docs

• CLI guide: https://docs.youka.io/en/cli
• JavaScript SDK: https://docs.youka.io/en/sdk

Discover capabilities and create lyric videos

youka capabilities --json
youka project quote ./reference.wav --duration 120 --kind lyric-video --mode transcribe --sync-model elevenlabs-transcription --lyrics "Optional recognition hints" --json
youka project create ./reference.wav --kind lyric-video --mode align --sync-model audioshake-alignment --lyrics "Supplied lyrics" --wait --json

--kind lyric-video skips separation and rejects --split-model. Omitted kind preserves karaoke behavior. All supported models are exposed with workflow and input requirements; models requiring isolated vocals cannot process an original track directly. --mode transcribe accepts recognition hints through --lyrics (or --text for project sync). --language-hint-mode auto|explicit controls the language policy. Wav2Vec2 is an alignment model.

Timings and version selection

youka project timings list proj_123 --json
youka project timings get proj_123 alignment_123 --json
youka project timings import proj_123 alignment_123 --body corrected-timings.json --json
youka project timings select proj_123 alignment_123 --expected-revision REVISION --expected-selection-revision SELECTION_REVISION --json
youka project versions proj_123 --json
youka project settings proj_123 --version-id version_123 --json
youka export create proj_123 --local --version-id version_123 --transparent --mute-all --fps 30 --output ./overlay.mov --json

corrected-timings.json contains { "alignment": { "items": [...] }, "expectedRevision": "...", "select": true, "expectedSelectionRevision": "..." }. Use --body - to read that JSON object from stdin. Timings replace the complete alignment, use absolute seconds, and preserve text and supported metadata. Invalid intervals and stale revisions fail rather than being silently repaired. Read results use the normal CLI JSON envelope; construct the import object from its data field rather than passing the whole envelope back.

Timing edits and selections start no AI task. --mute-all silences all existing stems and takes precedence over volume overrides; it does not promise removal of the audio stream. Transparent local exports use ProRes 4444 and do not incur cloud-export or alignment charges. Existing feature eligibility still applies. Line anticipation depends on the selected layout.

Deploy the matching API endpoints before publishing the updated CLI.