qwenspeak

qwenspeak

YAML-driven text-to-speech over SSH using Qwen3-TTS models.

For installation and deployment, see references/setup.md.

Security & safety

• Voice cloning requires consent. Reference audio (ref_audio) is biometric data of a real person's voice — only clone a voice you have explicit consent for. Cloning someone's voice without consent enables impersonation and fraud; never clone from audio scraped or supplied without the speaker's permission, and never use a clone to impersonate a specific named individual without their say-so. See Modes below.
• Every call leaves your host. scripts/qwenspeak.sh execs ssh to tts@$QWENSPEAK_HOST:$QWENSPEAK_PORT and pipes text, YAML job configs, and any audio you put/get over that connection — none of it stays local. Only point QWENSPEAK_HOST/QWENSPEAK_PORT at an instance you run or explicitly trust; see SSH Wrapper below.
• Both env vars are required — the wrapper hard-fails (QWENSPEAK_HOST not set / QWENSPEAK_PORT not set) if either is empty, so there is no silent unauthenticated fallback. Auth itself is SSH public-key only (see below).

Security model

qwenspeak is not a general-purpose shell. The instance runs inside a lockbox-hardened container, and this skill only ever talks to an instance you (or your operator) already run and trust:

• Key-auth only — SSH accepts public-key auth only (no passwords), connecting as a restricted tts@ user. There is no interactive shell and no PTY.
• Fixed command set — the SSH channel dispatches only the tts command plus lockbox's built-in, scoped file operations (the tables below). Anything else is refused; the remote never spawns a shell, so there is no command-injection surface.
• Work-dir confined — every file path resolves under the instance work directory; traversal is blocked. The sandbox cannot read or write your host filesystem.
• Consumer-only — this skill submits TTS jobs and moves files to/from a running instance. It never provisions, escalates, or installs anything on your machine (server setup is a separate, operator-side step — see setup.md).

SSH Wrapper

Use scripts/qwenspeak.sh for all commands. It handles host, port, and host key acceptance via QWENSPEAK_HOST and QWENSPEAK_PORT env vars.

scripts/qwenspeak.sh  [args]
scripts/qwenspeak.sh  < input_file
scripts/qwenspeak.sh  > output_file

External transmission. Every invocation sends its command, YAML job body, and any piped stdin/stdout (text, transcripts, audio bytes) over SSH to whatever QWENSPEAK_HOST/QWENSPEAK_PORT point at — data leaves your host. Point these only at a service you run or explicitly trust.

TTS Generation

Submit YAML, get a job UUID back immediately, poll for progress. Jobs run sequentially — one at a time, the rest queue up.

# Get the YAML template
scripts/qwenspeak.sh "tts print-yaml" > job.yaml

# Submit job
scripts/qwenspeak.sh "tts" < job.yaml
# {"id": "550e8400-...", "status": "queued", "total_steps": 3, "total_generations": 7}

# Check progress
scripts/qwenspeak.sh "tts get-job 550e8400"

# Follow job log
scripts/qwenspeak.sh "tts get-job-log 550e8400 -f"

# Download result
scripts/qwenspeak.sh "get hello.wav" > hello.wav

YAML Structure

Global settings + list of steps. Each step loads a model, runs all its generations, then unloads. Settings cascade: global > step > generation.

steps:
  - mode: custom-voice
    model_size: 1.7b
    speaker: Ryan
    language: English
    generate:
      - text: "Hello world"
        output: hello.wav
      - text: "I cannot believe this!"
        speaker: Vivian
        instruct: "Speak angrily"
        output: angry.wav

  - mode: voice-design
    generate:
      - text: "Welcome to our store."
        instruct: "A warm, friendly young female voice with a cheerful tone"
        output: welcome.wav

  - mode: voice-clone
    model_size: 1.7b
    ref_audio: ref.wav
    ref_text: "Transcript of reference"
    generate:
      - text: "First line in cloned voice"
        output: clone1.wav
      - text: "Second line"
        output: clone2.wav

Modes

custom-voice — Pick from 9 preset speakers. 1.7B supports emotion/style via instruct.

voice-design — Describe the voice in natural language via instruct. 1.7B only.

voice-clone — Clone from reference audio. Set ref_audio and ref_text at step level to reuse across generations. x_vector_only: true skips transcript.

Consent & privacy. ref_audio is a voice sample of a real person — treat it as sensitive personal data. Only clone a voice you have explicit consent to clone; an agent must NEVER clone a voice from audio of someone who hasn't agreed to it, and must never use a clone to impersonate a specific named individual (e.g. for fraud, harassment, or deceptive/synthetic-media purposes). If the user's request or the reference audio's provenance is unclear, ask before proceeding.

Emotion trick for cloned voices

Upload references with different emotions, use separate steps:

scripts/qwenspeak.sh "create-dir refs"
scripts/qwenspeak.sh "put refs/happy.wav" < me_happy.wav
scripts/qwenspeak.sh "put refs/angry.wav" < me_angry.wav

steps:
  - mode: voice-clone
    ref_audio: refs/happy.wav
    ref_text: "transcript of happy ref"
    generate:
      - text: "Great news everyone!"
        output: happy1.wav

  - mode: voice-clone
    ref_audio: refs/angry.wav
    ref_text: "transcript of angry ref"
    generate:
      - text: "This is unacceptable"
        output: angry1.wav

Job Management

scripts/qwenspeak.sh "tts list-jobs"              # list all
scripts/qwenspeak.sh "tts list-jobs --json"        # JSON output
scripts/qwenspeak.sh "tts get-job "            # job details
scripts/qwenspeak.sh "tts get-job-log "        # view log
scripts/qwenspeak.sh "tts get-job-log  -f"     # follow log
scripts/qwenspeak.sh "tts cancel-job "         # cancel

Statuses: queued → running → completed | failed | cancelled

Completed jobs auto-cleaned after 1 day, all jobs after 1 week. UUID prefixes work (e.g. first 8 chars).

File Operations

All paths relative to the work directory. Traversal blocked.

Speakers

YAML Options

All settings cascade: global > step > generation.