listenhub-voice

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

- User wants end-to-end audio from text (with sound effects baked in by the model)
- User wants a multi-voice dialogue where each line is assigned to a different voice
- User wants to clone a voice from a reference audio clip
- User wants to turn a reference **image** into audio (image → audio)
- User wants pure sound-effect generation from a text description
- User says "生成音频", "端到端音频", "图片转音频", "多音色对白", "参考音频克隆", "音效"

## When NOT to Use

- User just wants a single registered ListenHub voice to read text aloud (use `/tts`) —
  `/tts` is lower-latency for plain narration with already-registered ListenHub speakers
- User wants a podcast-style discussion with topic exploration (use `/podcast`)
- User wants music or a cover song (use `/music`)
- User wants a video (use `/video-gen`)
- User wants to transcribe audio/video to text (use `/asr`)

`/tts` vs `/listenhub-voice`: `/listenhub-voice` is the ListenHub-Voice-1.0 **end-to-end** model —
text or image into a finished audio track that can include sound effects, multi-voice
dialogue, and reference-audio voice cloning, with an optional `durationHint` to target
an approximate length. Plain single-voice narration with an already-registered ListenHub
voice can still go through `/tts`.

## Purpose

Generate end-to-end audio with the **ListenHub-Voice-1.0** model. One async task takes a text
script (and optionally voices, a reference image, audio params, and a duration hint) and
returns a finished audio file. Modes:

- **Plain text / sound effects** — no `voices`, no `image`. The model synthesizes the text
  and any sound effects described in it.
- **Single voice** — `voices` with 1 item, either a registered ListenHub speaker / Official
  `voice_type` (`type: speaker`) or a reference-audio clone (`type: reference`).
- **Multi-voice dialogue** — `voices` with 2–3 items; the script assigns each line with
  `@音频1` / `@音频2` prefixes in `voices` array order. Every item in a multi-voice request
  must be reference-audio-capable (official `voice_type` is single-voice only).
- **Reference-audio cloning** — `voices` item of `type: reference` pointing at a public
  audio URL to clone that voice.
- **Image → audio** — an `image` (url or data). **Mutually exclusive with `voices`.**

## Hard Constraints

- Always check CLI auth following `shared/cli-authentication.md`
- Follow `shared/cli-patterns.md` for CLI execution, errors, and interaction patterns
- Always read config following `shared/config-pattern.md` before any interaction
- Follow `shared/output-mode.md` for result presentation — `download` mode saves
  `{slug}.{ext}` (ext = `audioConfig.format`: `mp3` default / `wav` / `pcm` / `ogg_opus`)
  to cwd with dedupe per `shared/config-pattern.md` § Artifact Naming
- Always use the async pattern: submit returns a `taskId`, then **poll** the task endpoint
  until `success` / `failed` — never block waiting on a single call
- `image` and `voices` are **mutually exclusive** — never send both in one request
- Multi-voice (`voices` length > 1): every item must be reference-audio-capable; a Official
  `voice_type` (`type: speaker`) is single-voice only and will be rejected in a multi-voice request
- Never expose provider routing, credentials, internal status names, DAO, MongoDB, or
  callback internals — work only from the public 3-endpoint contract below

<HARD-GATE>
Use the AskUserQuestion tool for every multiple-choice step — do NOT print options
as plain text. Ask one question at a time. Wait for the user's answer before
proceeding to the next step. After all parameters are collected, summarize the
choices and ask the user to confirm. Do NOT call the generate endpoint until the
user has explicitly confirmed.
</HARD-GATE>

## Step -1: CLI Command Gate (ListenHub Voice HTTP fallback)

> ⚠️ **CLI status:** `listenhub-cli` does **not** yet ship a `listenhub-voice` subcommand.
> All examples below therefore call the OpenAPI HTTP contract directly with `curl` and a
> Bearer API Key (`lh_sk_...`). When a `listenhub-voice` CLI subcommand ships, this skill should
> be updated to prefer it (mirroring `/video-gen`'s `$CMD_PREFIX` pattern).

Detect whether a future CLI subcommand exists; if not, fall back to HTTP:

```bash
if listenhub listenhub-voice --help &>/dev/null; then
  LISTENHUB_VOICE_MODE="cli"
else
  echo "LISTENHUB_VOICE_COMMAND_UNAVAILABLE — falling back to OpenAPI HTTP (curl)"
  LISTENHUB_VOICE_MODE="http"
fi
```

For `http` mode, an OpenAPI API Key is required. Read it from config or env:

```bash
API_BASE="https://api.marswave.ai/openapi"   # OpenAPI base; see shared/cli-authentication.md
API_KEY="${LISTENHUB_API_KEY:-$(listenhub openapi config show --json 2>/dev/null | jq -r '.apiKey // empty')}"
if [ -z "$API_KEY" ]; then
  echo "需要 OpenAPI API Key（lh_sk_...）。请先用 listenhub openapi config set-key 配置，或设置 LISTENHUB_API_KEY 环境变量。"
fi
```

All requests authenticate with `Authorization: Bearer $API_KEY`.

## Step 0: Config Setup

Follow `shared/config-pattern.md` Step 0 (Zero-Question Boot).

**If file doesn't exist** — silently create with defaults and proceed:
```bash
mkdir -p ".listenhub/listenhub-voice"
echo '{"outputMode":"inline"}' > ".listenhub/listenhub-voice/config.json"
CONFIG_PATH=".listenhub/listenhub-voice/config.json"
CONFIG=$(cat "$CONFIG_PATH")
```

Session defaults (not persisted unless user reconfigures):
- model: `listenhub-voice-1.0` (the only valid value)
- audioConfig.format: `mp3`

**Do NOT ask any setup questions.** Proceed directly to the Interaction Flow.

**If file exists** — read config silently and proceed:
```bash
CONFIG_PATH=".listenhub/listenhub-voice/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/listenhub-voice/config.json"
CONFIG=$(cat "$CONFIG_PATH")
OUTPUT_MODE=$(echo "$CONFIG" | jq -r '.outputMode // "inline"')

From marswaveai/skills, MIT.

More from marswaveai/skills