Projects

A project holds the source media, lyrics, render settings, and exports for a karaoke or lyric video. Karaoke projects also contain separated stems.

`project create`

Create a new project from a local file or a URL.

youka project create <source> [options]

string

required

A local file path (./song.mp3) or an HTTP/HTTPS URL (https://example.com/song.mp4).

Options

Option	Description
`--kind <kind>`	`karaoke` or `lyric-video`. Defaults to `karaoke`.
`--title <title>`	Project title
`--mode <mode>`	`none`, `transcribe`, or `align`
`--lyrics <text>`	Lyrics text
`--lang <code>`	Language code
`--sync-model <model>`	Lyrics sync model
`--split-model <model>`	Stem separation model
`--max-video-quality <quality>`	Maximum video quality for URL sources: `720p`, `1080p`, `4k`, or `best`
`--preset <presetId>`	Apply a preset while creating the project
`--export`	Create an export after the project is ready
`--download`	Create an export, wait for it, and download it
`--output <path>`	Output path for `--download`

Examples

youka project create ./song.mp3 \
  --title "My Song" \
  --mode transcribe \
  --lang en \
  --wait \
  --json

youka project create "https://example.com/song.mp4" \
  --max-video-quality 4k \
  --download \
  --output ./karaoke.mp4 \
  --json

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

Rules:

If you pass lyrics and omit --mode, the CLI defaults to align
align requires lyrics
transcribe accepts optional reference lyrics. The model may return different text.
none does not accept lyrics
--kind lyric-video uses the original audio without stem separation and rejects --split-model. Omitting --kind preserves karaoke behavior.
--download implies --export
--max-video-quality only applies to HTTP/HTTPS URL sources. It defaults to 1080p, uses the best available quality up to that limit, and falls back to the best available format when the platform does not expose a capped stream.

`project list`

List all projects for the authenticated account.

youka project list
youka project list --json

`project quote`

Quote the credits required to create a project without creating the project.

youka project quote <source> [options]

source accepts the same local file path or HTTP/HTTPS URL forms as project create. Without --duration, the CLI uploads the source so the server can measure the media exactly, but it does not create a project.

Options

Option	Description
`--kind <kind>`	`karaoke` or `lyric-video`. Defaults to `karaoke`.
`--title <title>`	Project title
`--mode <mode>`	`none`, `transcribe`, or `align`
`--lyrics <text>`	Required text for `align`, optional guidance for `transcribe`
`--lang <code>`	Language code
`--sync-model <model>`	Lyrics sync model
`--split-model <model>`	Stem separation model
`--max-video-quality <quality>`	Maximum video quality for URL sources: `720p`, `1080p`, `4k`, or `best`
`--duration <seconds>`	Quote from a known duration without uploading the source

Examples:

youka project quote ./song.mp3 --mode transcribe --json
youka project quote https://example.com/song.mp4 --max-video-quality 4k --mode transcribe --json
youka project quote ./song.mp3 --duration 210 --mode none --json

`project show`

Get the current project state, including normalized state, pendingOperation, stems, settings, and exports.

youka project show <projectId>

string

required

The project ID returned by project create.

`project wait`

Poll a project until it reaches a terminal state.

youka project wait <projectId> --json

`project delete`

Delete a project and all its associated stems, lyrics, and exports.

youka project delete <projectId> --idempotency-key delete-<projectId>

Deletion is permanent. Pass --idempotency-key to make retries safe.

`project sync`

Re-run lyric transcription or alignment on an existing project.

youka project sync <projectId> [options]

Option	Description
`--mode <mode>`	`transcribe` or `align`
`--text <text>`	Lyrics text
`--lang <code>`	Language code
`--sync-model <model>`	Lyrics sync model

Example:

youka project sync $PROJECT_ID \
  --mode align \
  --text "$(cat lyrics.txt)" \
  --wait \
  --json

`project separate`

Re-run stem separation on an existing project.

youka project separate <projectId> [--split-model <model>]

Example:

youka project separate $PROJECT_ID --split-model audioshakeai --wait --json

`project settings`

Read or update the active project settings.

youka project settings <projectId>
youka project settings <projectId> --preset <presetId> --body ./settings.json

If neither --preset nor --body is present, the command returns the current settings. If either is present, it performs an update. Examples:

youka project settings $PROJECT_ID --json

youka project settings $PROJECT_ID \
  --preset preset_abc123 \
  --body ./project-settings.json \
  --json

`project stem list`

List stems for a project.

youka project stem list <projectId>
youka project stem list <projectId> --json

`project stem download`

Download one or more stem files to disk. Stems are downloaded in their original stored format; the CLI does not transcode them.

youka project stem download <projectId> <stemId> --output ./stems
youka project stem download <projectId> --type instrumental --output ./stems
youka project stem download <projectId> --type original --type backing-vocals --type vocals --output ./stems
youka project stem download <projectId> --all --output ./stems

Supported --type values are original, instrumental, vocals, and backing_vocals. The CLI also accepts backing-vocals, backingVocals, and backingvocals as aliases.

What’s next

Exports - render the finished karaoke
Presets - manage reusable render configurations
Render settings reference - shared preset and settings fields

Capabilities, versions, and timings

youka capabilities --json returns model IDs, supported workflows, text handling, language support, and account eligibility. Wav2Vec2 is an alignment model. ElevenLabs Scribe is a transcription model. Models that require isolated vocals need a karaoke workflow with a separation model that produces vocals.

youka capabilities --json
youka project create ./song.wav --kind lyric-video --mode transcribe --sync-model elevenlabs-transcription --json
youka project quote ./song.wav --kind lyric-video --mode transcribe --sync-model elevenlabs-transcription --json
youka project versions proj_example --json
youka project settings proj_example --version-id ver_example --json
youka project timings list proj_example --json
youka project timings get proj_example aln_example --json
youka project timings import proj_example aln_example --body corrected-request.json --json
youka project timings select proj_example aln_example --expected-revision "$ALIGNMENT_REVISION" --expected-selection-revision "$SELECTION_REVISION" --json

project settings --version-id reads or updates the chosen version. Omitting the flag uses the primary version. Timing imports replace the complete alignment without a processing job or credit hold. The JSON body contains alignment and expectedRevision. Atomic save-and-select also needs select: true and expectedSelectionRevision. A stale token returns HTTP 409. Fetch and compare the current values before trying another edit. See Automate lyric videos for request files, timing validation, and resumable catalogue processing.

Overview

Reference

`project create`

Options

Examples

`project list`

`project quote`

Options

`project show`

`project wait`

`project delete`

`project sync`

`project separate`

`project settings`

`project stem list`

`project stem download`

What’s next

Capabilities, versions, and timings

​project create

​Options

​Examples

​project list

​project quote

​Options

​project show

​project wait

​project delete

​project sync

​project separate

​project settings

​project stem list

​project stem download

​What’s next

​Capabilities, versions, and timings

`project create`

Options

Examples

`project list`

`project quote`

Options

`project show`

`project wait`

`project delete`

`project sync`

`project separate`

`project settings`

`project stem list`

`project stem download`

What’s next

Capabilities, versions, and timings