# Mureka music and speech

VideoClaw connects to Mureka through useapi.net for songs, instrumental music,
narration and dialogue. It uses the existing soundtrack selection and audio
artifacts, so generated audio can be previewed and used in a film.

## Connect your account

1. Complete [useapi's Mureka setup](https://useapi.net/docs/start-here/setup-mureka).
   You need both a useapi subscription and a Mureka account. Signing up alone
   does not link them: use the setup page's **Add account** form. The provider
   supports email/password or session-token linking.
2. Save your complete useapi token in your **workspace** `.env.local`, not in
   the package or a tracked source file. Existing `USEAPI_API_TOKEN` values work
   across useapi services if the subscription permits Mureka access.

   ```dotenv
   USEAPI_API_TOKEN=your-complete-useapi-token
   # Optional when one Mureka account is linked; required when several exist:
   VCLAW_MUREKA_ACCOUNT=your-mureka-account-id
   # Optional; omission uses the provider's account default:
   VCLAW_MUREKA_MODEL=V9.5
   # Optional default for speech, from the voice lookup below:
   VCLAW_MUREKA_VOICE_ID=your-numeric-voice-id
   ```

3. Verify without spending credits:

   ```sh
   vclaw video mureka --root /path/to/workspace
   vclaw video mureka --voices --root /path/to/workspace
   ```

The account check omits credentials. A token's presence only makes the backend
locally available; it does not prove the linked account or paid plan is ready.
For HTTP 401/403 check the complete token and useapi subscription. For account
errors, reconnect through the setup page. Do not paste passwords into prompts.

## Generate music

With an existing project, preview an instrumental request first:

```sh
vclaw video soundtrack --project my-film --root /path/to/workspace --backends mureka --prompt "Warm cinematic strings and soft piano" --instrumental --dry-run
```

For a live generation, replace `--dry-run` with `--confirm-spend` after approving
the generation spend. Explicitly use `--backends mureka` to select only Mureka;
omitting the flag runs every available music backend.

- With `--instrumental`, the prompt limit is 1,000 characters.
- With `--lyrics "[Verse] ..."`, the lyrics limit is 5,000 characters and the
  musical description (`--prompt`) limit is 1,000 characters.
- With neither flag, Mureka generates a vocal song from the prompt (up to
  3,000 characters).
- Combining lyrics and instrumental is rejected before submission.
- Supported model settings: `V9.5`, `V9`, `V8`, `O2`, `V7.6`, `V7.5`.
  Availability depends on the Mureka plan.
- `--duration` is a dry-run estimate. The provider chooses the live song length;
  VideoClaw records its actual duration rather than promising an exact length.

The first returned song is saved as `artifacts/audio/soundtrack-mureka.mp3`.
Both returned songs' IDs and URLs are retained in the adjacent `.mureka.json`
receipt. Select the soundtrack for the project without regenerating:

```sh
vclaw video soundtrack --project my-film --root /path/to/workspace --select mureka
```

## Narration and dialogue

Use a numeric ID returned by `video mureka --voices`, or configure
`VCLAW_MUREKA_VOICE_ID`. Voice names such as “Sarah” are not IDs.

```sh
vclaw video narrate --project my-film --root /path/to/workspace --backend mureka-tts --voice 12345 --text "Our story begins here." --dry-run
vclaw video dialogue --project my-film --root /path/to/workspace --backend mureka-tts --voice 12345 --turns "Alex: Hello. || Sam: Welcome." --dry-run
```

Replace the example voice ID with a real one. Speech is limited to 5,000
characters per generation. Dialogue creates one clip per turn; library callers
can supply a different `voice` for each turn. Outputs are MP3. Live generation
requires `--confirm-spend`.

## Recover a generation

The receipt `<audio-path>.mureka.json` is saved immediately after submission.
If polling or downloading fails, inspect the recorded job instead of generating
again:

```sh
vclaw video mureka --job 'the-recorded-job-id' --root /path/to/workspace
```

Completed job results contain download URLs. useapi retains job records for
seven days. A network failure during submission can leave the outcome unknown;
check the provider's job history before resubmitting. VideoClaw never retries a
paid submission automatically. Polling defaults to 120 checks at three-second
intervals, configurable with `VCLAW_MUREKA_POLL_MAX_ATTEMPTS` and
`VCLAW_MUREKA_POLL_INTERVAL_MS`. Downloads never receive the useapi token.

This integration exposes music and speech. Mureka's API does not document a
dedicated sound-effects endpoint; VideoClaw's existing `sfx` backend remains
available. Stem extraction, song editing, reference uploads and voice cloning
are separate Mureka features not exposed by these commands.

Source: [Mureka API v1](https://useapi.net/docs/api-mureka-v1).

## Download a generated song's stems

`vclaw video mureka --stems <song_id> --out <zip-path> [--account <id>]`

Downloads the existing Mureka song's stem ZIP through useapi; it does not generate a song. The linked account needs stem-download entitlement. The original song ID is required; this endpoint does not separate arbitrary uploaded tracks.

The command saves the archive and a `.mureka.json` sidecar containing the provider, song ID, SHA-256, byte count and download timestamp. A matching archive is reused without another request. Existing mismatched or incomplete outputs are refused; choose a new output path. Downloads check the ZIP signature but do not extract or validate individual stems. A separate extraction and audio verification step is still required before using these files for rendering. CDN requests do not carry the API token, and failed submissions are not automatically retried.