# Humaneness Voice Small 1.1 Alpha: prompting guide This guide applies to the [Small 1.1 Alpha base](https://huggingface.co/laion/Humaneness-Voice-Small-1.1-Alpha) and its [RL rank-128 v1 adapter](https://huggingface.co/laion/Humaneness-Voice-Small-1.1-Alpha-RL-r128-v1). Both use the same structured prompt conventions. The adapter has its own loader and sampling settings; see [Base versus RL](#base-versus-rl). ## Quick start 1. Put **exactly the words to speak** in `--text`, in the desired language. 2. Put the English performance directions and a matching annotated script in `--prompt`. 3. Choose **one** voice condition: `--reference-wav`, `--alias`, or neither. 4. Set `--language` and `--frames`; choose a seed for repeatable comparisons. The recommended acting format is: ```text GENERAL: Warm, relieved and naturally conversational. SCRIPT: (softly, with relief) [2.4 seconds duration] We finally made it home. [0.4 seconds pause] (warmly, smiling) [2.0 seconds duration] I am glad we are together. ``` The matching separate spoken text is: ```text We finally made it home. I am glad we are together. ``` Use the exact same spoken words and order in the script and `--text`. The parentheses and square brackets are **directions**, not words to be spoken. This structured script does not require quotation marks around the spoken words. If the two text fields disagree, the result is unpredictable: do not rely on the model to resolve the conflict. ## What the fields mean | Part | Purpose | Example | | --- | --- | --- | | `GENERAL:` | Overall voice, recording and performance description in English. | `A calm, warm voice, speaking naturally and with gratitude.` | | `SCRIPT:` | The literal speech, with optional local cues in order. | See the two-sentence example above. | | `(direction)` | How the following speech segment should be performed. | `(quietly, with fear)` | | `[N seconds duration]` | Requested duration of the following speech segment. | `[3.7 seconds duration]` | | `[N seconds pause]` | A pause at that position in the script. | `[0.4 seconds pause]` | | `(vocal burst, N seconds)` | A non-verbal event at that position. | `(chuckle, 0.5 seconds)` | | `--text` | Literal spoken transcript, without direction, duration or burst markup. | `We finally made it home.` | One script line can describe a sentence or shorter phrase. Use a separate direction and duration for each phrase you want to control. Place pauses and bursts between the words where they should occur. For example: ```text GENERAL: A friendly, amused voice in a relaxed conversation. SCRIPT: (amused) [1.8 seconds duration] That was unexpected. (chuckle, 0.5 seconds) [0.3 seconds pause] (still amused, gently) [2.1 seconds duration] You really surprised me. ``` The corresponding `--text` is `That was unexpected. You really surprised me.` A burst is a requested sound, not a guarantee that it will be realized. Its parentheses do not replace the speaker's dialogue. For best clarity, use a short label and an explicit duration for the burst. ## How much direction to provide The fine-tuning mix included (1) GENERAL plus inline SCRIPT directions, (2) GENERAL plus a plain SCRIPT, and (3) inline SCRIPT without GENERAL. A small fraction also omitted the control cues. Start with the full structured format above; then try simpler variants if the model reads or confuses directions. Directions are written in English; the spoken words in `SCRIPT:` and `--text` remain in the chosen language. **Overall direction, plain script:** ```text GENERAL: A quiet, anxious voice, trying to remain composed. SCRIPT: Ich glaube, wir sollten jetzt nach Hause gehen. ``` **Local direction without a GENERAL line:** ```text SCRIPT: (quietly, anxiously) [3.1 seconds duration] Ich glaube, wir sollten jetzt nach Hause gehen. ``` For these German examples set `--language de` and use the identical German sentence as `--text`. Names, emotions and accent words in a direction do not belong in the spoken text unless the speaker is meant to say them. Avoid contradictory instructions such as `whisper` and `shout` at the same time unless deliberately testing a transition. Earlier Small pretraining also used `CAPTION: ...` / `TRANSCRIPT: ...` examples and other captions where available. This 1.1 acting continuation primarily used the GENERAL/SCRIPT views above. Caption/transcript and free-form director-style prompts can be explored, but their behaviour here is less well established; do not assume DramaBox-style quoted text or a particular free-form instruction will be followed reliably. ## Voice identity: reference, name, or neither The CLI makes `--reference-wav` and `--alias` mutually exclusive. * **Reference:** `--reference-wav clean-speaker.wav` supplies audio separately from the prompt. Prefer a distinct, clean, single-speaker recording of **5–15 seconds**, without music or overlap. The loader crops the waveform to at most 15 seconds **before** codec encoding and warns if it is shorter than five seconds. `--reference-max-seconds` accepts 5–15, default 15. More reference duration does not guarantee better speaker similarity. * **Known alias:** `--alias Alice` uses a learned voice label; it is not appended to the spoken transcript. The base repository's [`voices.json`](https://huggingface.co/laion/Humaneness-Voice-Small-1.1-Alpha/blob/main/voices.json) lists available pseudonyms and other aliases. Examples include `Alice`, `Bob` and `Gaston`. Gaston examples were trained with `French Accent` in GENERAL. Unseen names are not guaranteed to select a consistent voice. * **Neither:** omit both flags for an unconditioned voice. A GENERAL description can request broad properties, but an exact speaker identity is not guaranteed. The RL v1 training paired **reference** and **no-reference/no-name** conditions. Alias prompting remains available in its loader, but was an evaluation-only condition for that RL run; its quality and identity consistency may differ from the base. ## Duration and frame budget There are **12.5 semantic audio frames per second**, or 80 ms per frame. `--frames` supplies the desired frame count to the model; start with approximately `round(total_seconds × 12.5)`. The CLI accepts 2–750 frames. For example, 60 frames is about 4.8 seconds, while 75 frames is about 6 seconds. For a timed script, use a frame budget broadly consistent with the sum of requested speech durations, pauses and bursts. Sentence-level timing and the frame budget are **conditioning requests**, not precise guarantees. The generation call allows up to `frames + 45` new frames and may stop earlier; measure the output rather than assuming the requested duration was met. Timing, text accuracy and emotional expression can vary with seed. ## Working CLI examples Download the full base repository and its separately required MOSS v2 codec; install its listed dependencies. The tested path requires a CUDA GPU. A local codec snapshot may be passed with `--codec-path /path/to/codec`. ```bash hf download laion/Humaneness-Voice-Small-1.1-Alpha --local-dir model python model/infer.py --model-dir model --language en \ --reference-wav clean-speaker.wav \ --text 'We finally made it home. I am glad we are together.' \ --prompt 'GENERAL: Warm, relieved and naturally conversational. SCRIPT: (softly, with relief) [2.4 seconds duration] We finally made it home. [0.4 seconds pause] (warmly, smiling) [2.0 seconds duration] I am glad we are together.' \ --frames 60 --seed 777 --output example.wav ``` To use a known name instead, replace `--reference-wav clean-speaker.wav` with `--alias Alice`. To use neither, remove the reference flag. Use actual newlines in the prompt, as shown in the shell examples. The RL repository includes its pinned base in `base/`; use its **top-level** loader. This is a custom attention LoRA, not a standard PEFT adapter: ```bash hf download laion/Humaneness-Voice-Small-1.1-Alpha-RL-r128-v1 --local-dir adapter python adapter/infer.py --adapter-dir adapter --language de \ --reference-wav clean-speaker.wav \ --text 'Ich glaube, wir sollten jetzt nach Hause gehen.' \ --prompt 'GENERAL: A quiet, anxious voice, trying to remain composed. SCRIPT: (quietly, anxiously) [3.1 seconds duration] Ich glaube, wir sollten jetzt nach Hause gehen.' \ --frames 40 --seed 777 --output example-rl.wav ``` Both loaders support `en`, `de`, `fr`, `nl` and `es`; language quality is experimental. The RL training and its published comparison primarily cover English and German. Keep text, prompt, reference, frame budget and seed matched when comparing checkpoints. ## Base versus RL The base CLI uses BF16 inference and audio temperature 1.0. The RL loader applies the adapter to the pinned, bundled base using its documented FP32 policy path and audio temperature 0.7. It verifies weight hashes and uses `adapter.safetensors`; downloading only the adapter file is insufficient. Different inference settings also affect the output, so a default base-versus-RL comparison does not isolate only the adapter. The [matched listening grid](https://laion-humaneness-voice-1-1-alpha-listening.static.hf.space/listening.html?model=rl) includes matching FP32/temperature-0.7 controls. For training details and additional examples, see the model card, [TRAINING.md](https://huggingface.co/laion/Humaneness-Voice-Small-1.1-Alpha/blob/main/TRAINING.md), and the prompts in the listening grid. Obtain permission to use a reference voice, disclose synthesized speech, and follow the model card's research-use guidance.