### Install HeartLib Locally

Source: https://github.com/heartmula/heartlib/blob/main/README.md

Clone the repository and install the HeartLib package in editable mode. This is the recommended setup for local deployment.

```bash
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib
pip install -e .
```

--------------------------------

### Example Lyrics Format

Source: https://github.com/heartmula/heartlib/blob/main/README.md

This is the recommended format for lyrics files. It includes sections like [Intro], [Verse], [Prechorus], [Chorus], [Bridge], and [Outro].

```txt
[Intro]

[Verse]
The sun creeps in across the floor
I hear the traffic outside the door
The coffee pot begins to hiss
It is another morning just like this

[Prechorus]
The world keeps spinning round and round
Feet are planted on the ground
I find my rhythm in the sound

[Chorus]
Every day the light returns
Every day the fire burns
We keep on walking down this street
Moving to the same steady beat
It is the ordinary magic that we meet

[Verse]
The hours tick deeply into noon
Chasing shadows,chasing the moon
Work is done and the lights go low
Watching the city start to glow

[Bridge]
It is not always easy,not always bright
Sometimes we wrestle with the night
But we make it to the morning light

[Chorus]
Every day the light returns
Every day the fire burns
We keep on walking down this street
Moving to the same steady beat

[Outro]
Just another day
Every single day
```

--------------------------------

### Run Music Generation Example

Source: https://github.com/heartmula/heartlib/blob/main/README.md

Execute this Python script to generate music. It requires the path to the downloaded models and can be conditioned on lyrics and tags from the assets folder. The output is saved as an MP3 file.

```python
python ./examples/run_music_generation.py --model_path=./ckpt --version="3B"
```

--------------------------------

### Example Tags Format

Source: https://github.com/heartmula/heartlib/blob/main/README.md

Tags should be comma-separated without spaces. Refer to the provided issue for more examples and guidance on tag usage.

```txt
piano,happy,wedding,synthesizer,romantic
```

--------------------------------

### Enable Lazy Loading for Single GPU

Source: https://github.com/heartmula/heartlib/blob/main/README.md

For single GPU setups experiencing CUDA out of memory errors, enable lazy loading with `--lazy_load true`. This loads modules on demand and unloads them after inference to conserve memory.

```bash
python ./examples/run_music_generation.py --model_path=./ckpt --version="3B" --lazy_load true
```

--------------------------------

### Distribute Model Components Across GPUs

Source: https://github.com/heartmula/heartlib/blob/main/README.md

If you have multiple GPUs, you can specify different devices for HeartMuLa and HeartCodec to optimize memory usage. For example, use `cuda:0` for HeartMuLa and `cuda:1` for HeartCodec.

```bash
python ./examples/run_music_generation.py --model_path=./ckpt --version="3B" --mula_device cuda:0 --codec_device cuda:1
```

--------------------------------

### Download Pretrained Checkpoints

Source: https://github.com/heartmula/heartlib/blob/main/README.md

Download pretrained model checkpoints from Hugging Face or ModelScope. Ensure you specify the correct local directory for storage.

```bash
# if you are using huggingface
hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen'
hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year'
hf download --local-dir './ckpt/HeartCodec-oss' HeartMuLa/HeartCodec-oss-20260123
```

--------------------------------

### CLI: Custom Music Generation Parameters

Source: https://context7.com/heartmula/heartlib/llms.txt

Generate music with custom lyrics, tags, output path, and generation parameters via the CLI. Ensure specified files exist.

```bash
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --lyrics=./my_lyrics.txt \
    --tags=./my_tags.txt \
    --save_path=./output/my_song.mp3 \
    --max_audio_length_ms=180000 \
    --cfg_scale=2.0 \
    --temperature=0.95 \
    --topk=40
```

--------------------------------

### Download HeartMula Models with Modelscope

Source: https://github.com/heartmula/heartlib/blob/main/README.md

Use these commands to download the necessary pretrained models for HeartMula. Ensure you specify the correct model name and a local directory for storage.

```bash
modelscope download --model 'HeartMuLa/HeartMuLaGen' --local_dir './ckpt'
```

```bash
modelscope download --model 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year' --local_dir './ckpt/HeartMuLa-oss-3B'
```

```bash
modelscope download --model 'HeartMuLa/HeartCodec-oss-20260123' --local_dir './ckpt/HeartCodec-oss'
```

--------------------------------

### Download Checkpoints with Hugging Face CLI

Source: https://context7.com/heartmula/heartlib/llms.txt

Download model checkpoints from Hugging Face Hub for HeartMuLaGen and HeartCodec. Ensure the local directory structure is maintained.

```bash
# Download checkpoints from Hugging Face
hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen'
hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year'
hf download --local-dir './ckpt/HeartCodec-oss' HeartMuLa/HeartCodec-oss-20260123
```

--------------------------------

### Generate Music with HeartMuLaGenPipeline

Source: https://context7.com/heartmula/heartlib/llms.txt

Run the full music generation pipeline, including text preprocessing, token generation, audio decoding, and saving to MP3. Ensure the pipeline is loaded before calling.

```python
import torch
from heartlib import HeartMuLaGenPipeline

pipe = HeartMuLaGenPipeline.from_pretrained(
    "./ckpt",
    device=torch.device("cuda"),
    dtype={"mula": torch.bfloat16, "codec": torch.float32},
    version="3B",
)
```

--------------------------------

### CLI: Multi-GPU Music Generation

Source: https://context7.com/heartmula/heartlib/llms.txt

Configure music generation to use multiple GPUs, assigning HeartMuLa to one and HeartCodec to another. Specify data types for each device.

```bash
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --mula_device=cuda:0 \
    --codec_device=cuda:1 \
    --mula_dtype=bf16 \
    --codec_dtype=fp32
```

--------------------------------

### HeartMuLaGenPipeline.from_pretrained

Source: https://context7.com/heartmula/heartlib/llms.txt

Loads the HeartMuLa music generation pipeline, including the language model and audio decoder, from a local checkpoint directory. It supports various configurations for device placement, data types, and lazy loading to optimize memory usage.

```APIDOC
## HeartMuLaGenPipeline.from_pretrained

### Description
Loads HeartMuLa (language model backbone) and HeartCodec (audio decoder) from a local checkpoint directory. Supports placing each component on a separate CUDA device and lazy-loading to minimize peak GPU memory.

### Method
`HeartMuLaGenPipeline.from_pretrained(
    pretrained_path: str,
    device: Union[torch.device, Dict[str, torch.device]],
    dtype: Dict[str, torch.dtype],
    version: str,
    lazy_load: bool = False
)

### Parameters
#### Path Parameters
- **pretrained_path** (str) - Required - Path to the local checkpoint directory.

#### Device Configuration
- **device** (Union[torch.device, Dict[str, torch.device]]) - Required - Specifies the CUDA device(s) for the components. Can be a single `torch.device` for all components or a dictionary mapping component names ('mula', 'codec') to specific devices.

#### Data Type Configuration
- **dtype** (Dict[str, torch.dtype]) - Required - A dictionary specifying the data types for 'mula' (recommended: `torch.bfloat16`) and 'codec' (recommended: `torch.float32`).

#### Version
- **version** (str) - Required - The version of the HeartMuLa model to load (e.g., "3B").

#### Lazy Loading
- **lazy_load** (bool) - Optional - If `True`, unloads each component after its inference phase to save memory. Automatically disabled for multi-GPU configurations.

### Request Example
```python
import torch
from heartlib import HeartMuLaGenPipeline

# Standard single-GPU load
pipe = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),
    dtype={
        "mula": torch.bfloat16,
        "codec": torch.float32,
    },
    version="3B",
    lazy_load=False,
)

# Multi-GPU load
pipe_multi = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device={
        "mula":  torch.device("cuda:0"),
        "codec": torch.device("cuda:1"),
    },
    dtype={
        "mula":  torch.bfloat16,
        "codec": torch.float32,
    },
    version="3B",
    lazy_load=False,
)

# Memory-saving lazy load
pipe_lazy = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),
    dtype={"mula": torch.bfloat16, "codec": torch.float32},
    version="3B",
    lazy_load=True,
)
```
```

--------------------------------

### CLI: Memory-Constrained Music Generation

Source: https://context7.com/heartmula/heartlib/llms.txt

Optimize music generation for memory-constrained single GPUs by enabling lazy loading of modules. Specify data types for HeartMuLa and HeartCodec.

```bash
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --lazy_load=true \
    --mula_dtype=bf16 \
    --codec_dtype=fp32
```

--------------------------------

### Specify Custom Lyrics File

Source: https://github.com/heartmula/heartlib/blob/main/README.md

To use your own lyrics, provide the path to your lyrics file using the `--lyrics` argument. The default path is `./assets/lyrics.txt`.

```bash
python ./examples/run_music_generation.py --model_path=./ckpt --version="3B" --lyrics my_awesome_lyrics.txt
```

--------------------------------

### Music Generation with File Inputs

Source: https://context7.com/heartmula/heartlib/llms.txt

Generate music using lyrics and tags from specified text files. Ensure the input files exist and are correctly formatted.

```python
with torch.no_grad():
    pipe(
        inputs={
            "lyrics": "./assets/lyrics.txt",   # path to a .txt file, OR a raw lyrics string
            "tags":   "./assets/tags.txt",     # path to a .txt file, OR a raw tags string
            # "ref_audio": ...                 # not yet supported
        },
        max_audio_length_ms=240_000,   # max 4 minutes; generation stops at EOS token
        save_path="./assets/output.mp3",
        topk=50,                       # top-k sampling
        temperature=1.0,               # sampling temperature
        cfg_scale=1.5,                 # classifier-free guidance scale (1.0 = no guidance)
    )

print("Generated music saved to ./assets/output.mp3")
```

--------------------------------

### Download Checkpoints with ModelScope CLI

Source: https://context7.com/heartmula/heartlib/llms.txt

Download model checkpoints from ModelScope for HeartMuLaGen and HeartCodec. Ensure the local directory structure is maintained.

```bash
# Or from ModelScope
modelscope download --model 'HeartMuLa/HeartMuLaGen' --local_dir './ckpt'
modelscope download --model 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year' --local_dir './ckpt/HeartMuLa-oss-3B'
modelscope download --model 'HeartMuLa/HeartCodec-oss-20260123' --local_dir './ckpt/HeartCodec-oss'
```

--------------------------------

### Download HeartTranscriptor Checkpoint

Source: https://github.com/heartmula/heartlib/blob/main/examples/README.md

Use these commands to download the pre-trained HeartTranscriptor model checkpoint. Specify the local directory for saving the model files.

```bash
hf download --local_dir './ckpt/HeartTranscriptor-oss' 'HeartMuLa/HeartTranscriptor-oss'
```

```bash
modelscope download --model 'HeartMuLa/HeartTranscriptor-oss' --local_dir './ckpt/HeartTranscriptor-oss'
```

--------------------------------

### Music Generation with Inline String Inputs

Source: https://context7.com/heartmula/heartlib/llms.txt

Generate music using lyrics and tags provided directly as strings. This method avoids the need for separate input files.

```python
lyrics_str = """
[Verse]
The sun creeps in across the floor
I hear the traffic outside the door

[Chorus]
Every day the light returns
Every day the fire burns"""

tags_str = "piano,happy"   # comma-separated, no spaces; all lowercase

with torch.no_grad():
    pipe(
        inputs={"lyrics": lyrics_str, "tags": tags_str},
        max_audio_length_ms=120_000,   # ~2 minutes
        save_path="./my_song.mp3",
        cfg_scale=2.0,                 # higher = stronger style adherence
        temperature=0.9,
        topk=40,
    )
```

--------------------------------

### Run Lyrics Transcription Script

Source: https://github.com/heartmula/heartlib/blob/main/examples/README.md

Execute the Python script to perform lyrics transcription. By default, it uses an MP3 file located at `./assets/output.mp3`. Use the `--music_path` argument to specify a different input music file.

```python
python ./examples/run_lyrics_transcription.py --model_path=./ckpt
```

--------------------------------

### Inspect HeartMuLa Configuration

Source: https://context7.com/heartmula/heartlib/llms.txt

Load a HeartMuLa model and inspect its configuration attributes such as backbone flavor, decoder flavor, text and audio vocabulary sizes, and the number of audio codebooks. Verify the checkpoint path.

```python
from heartlib.heartmula.configuration_heartmula import HeartMuLaConfig
from heartlib.heartmula.modeling_heartmula import HeartMuLa

mula = HeartMuLa.from_pretrained("./ckpt/HeartMuLa-oss-3B", device_map="cuda")

mcfg: HeartMuLaConfig = mula.config
print(mcfg.backbone_flavor)      # "llama-3B"
print(mcfg.decoder_flavor)       # "llama-300M"
print(mcfg.text_vocab_size)      # 128256
print(mcfg.audio_vocab_size)     # 8197
print(mcfg.audio_num_codebooks)  # 8
```

--------------------------------

### Inspect HeartCodec Configuration

Source: https://context7.com/heartmula/heartlib/llms.txt

Load a HeartCodec model and inspect its configuration attributes like sample rate, number of quantizers, codebook size, and causality. Ensure the checkpoint path is correct.

```python
from heartlib.heartcodec.configuration_heartcodec import HeartCodecConfig
from heartlib.heartcodec.modeling_heartcodec import HeartCodec

# Inspect a loaded checkpoint's configuration
codec = HeartCodec.from_pretrained("./ckpt/HeartCodec-oss", device_map="cuda")

cfg: HeartCodecConfig = codec.config
print(cfg.sample_rate)       # 48000
print(cfg.num_quantizers)    # 8
print(cfg.codebook_size)     # 8192
print(cfg.causal)            # True
print(cfg.downsample_factors)  # [3, 4, 4, 4, 5] → overall downsampling = 960× = 48000/50
```

--------------------------------

### HeartMuLaGenPipeline CLI Usage

Source: https://context7.com/heartmula/heartlib/llms.txt

Command-line interface for the HeartMuLa music generation pipeline, covering various parameters for customization.

```APIDOC
## HeartMuLaGenPipeline CLI Usage

Full command-line interface covering all generation parameters.

```bash
# Basic generation with default assets
python ./examples/run_music_generation.py --model_path=./ckpt --version="3B"

# Custom lyrics / tags / output path
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --lyrics=./my_lyrics.txt \
    --tags=./my_tags.txt \
    --save_path=./output/my_song.mp3 \
    --max_audio_length_ms=180000 \
    --cfg_scale=2.0 \
    --temperature=0.95 \
    --topk=40

# Multi-GPU: HeartMuLa on cuda:0, HeartCodec on cuda:1
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --mula_device=cuda:0 \
    --codec_device=cuda:1 \
    --mula_dtype=bf16 \
    --codec_dtype=fp32

# Memory-constrained single GPU (lazy load)
python ./examples/run_music_generation.py \
    --model_path=./ckpt \
    --lazy_load=true \
    --mula_dtype=bf16 \
    --codec_dtype=fp32
```

| Argument | Default | Description |
|---|---|---|
| `--model_path` | *(required)* | Path to checkpoint directory |
| `--version` | `3B` | Model size: `3B` or `7B` (7B not yet released) |
| `--lyrics` | `./assets/lyrics.txt` | Lyrics file path or raw string |
| `--tags` | `./assets/tags.txt` | Tags file path or raw string |
| `--save_path` | `./assets/output.mp3` | Output audio path |
| `--max_audio_length_ms` | `240000` | Max generation length in ms |
| `--topk` | `50` | Top-k sampling |
| `--temperature` | `1.0` | Sampling temperature |
| `--cfg_scale` | `1.5` | Classifier-free guidance scale |
| `--mula_device` | `cuda` | Device for HeartMuLa |
| `--codec_device` | `cuda` | Device for HeartCodec |
| `--mula_dtype` | `bf16` | Dtype for HeartMuLa |
| `--codec_dtype` | `fp32` | Dtype for HeartCodec |
| `--lazy_load` | `false` | Lazy-load modules to save VRAM |
```

--------------------------------

### Load HeartTranscriptor Pipeline

Source: https://context7.com/heartmula/heartlib/llms.txt

Load the HeartTranscriptor ASR pipeline from a local checkpoint directory. Ensure the checkpoint path is correct and contains the necessary model files.

```python
import torch
from heartlib import HeartTranscriptorPipeline

# Checkpoint directory must contain ./ckpt/HeartTranscriptor-oss/
pipe = HeartTranscriptorPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),
    dtype=torch.float16,
)
# Pipeline is configured with chunk_length_s=30, batch_size=16 internally
```

--------------------------------

### Transcribe Audio File with Pipeline

Source: https://context7.com/heartmula/heartlib/llms.txt

Use the `pipe` object to transcribe an audio file. Ensure the audio file exists at the specified path. For best results, separate vocals from the mix first using demucs.

```python
with torch.no_grad():
    result = pipe(
        "./assets/output.mp3",
        **{
            "max_new_tokens": 256,
            "num_beams": 2,
            "task": "transcribe",
            "condition_on_prev_tokens": False,
            "compression_ratio_threshold": 1.8,
            "temperature": (0.0, 0.1, 0.2, 0.4),   # fallback temperature schedule
            "logprob_threshold": -1.0,
            "no_speech_threshold": 0.4,
        },
    )

print(result)
```

```bash
# CLI equivalent
python ./examples/run_lyrics_transcription.py \
    --model_path=./ckpt \
    --music_path=./assets/output.mp3
```

```bash
pip install demucs
python -m demucs --two-stems=vocals ./assets/output.mp3
# then transcribe separated/htdemucs/output/vocals.wav
```

--------------------------------

### Load HeartMuLaGenPipeline (Multi-GPU)

Source: https://context7.com/heartmula/heartlib/llms.txt

Load the music generation pipeline across multiple CUDA devices. Lazy loading is automatically disabled for multi-GPU configurations.

```python
# --- Multi-GPU load (e.g. 2× RTX 4090) ---
pipe_multi = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device={
        "mula":  torch.device("cuda:0"),
        "codec": torch.device("cuda:1"),
    },
    dtype={
        "mula":  torch.bfloat16,
        "codec": torch.float32,
    },
    version="3B",
    lazy_load=False,   # automatically disabled for multi-GPU
)
```

--------------------------------

### HeartTranscriptorPipeline.from_pretrained

Source: https://context7.com/heartmula/heartlib/llms.txt

Loads the HeartTranscriptor Whisper-based model from a local checkpoint. The pipeline extends HuggingFace `AutomaticSpeechRecognitionPipeline` with chunked (30 s) long-form transcription support.

```APIDOC
## HeartTranscriptorPipeline.from_pretrained — Load the lyrics transcription pipeline

Loads the HeartTranscriptor Whisper-based model from a local checkpoint. The pipeline extends HuggingFace `AutomaticSpeechRecognitionPipeline` with chunked (30 s) long-form transcription support.

```bash
# Download checkpoint
hf download --local_dir './ckpt/HeartTranscriptor-oss' 'HeartMuLa/HeartTranscriptor-oss'
# or
modelscope download --model 'HeartMuLa/HeartTranscriptor-oss' --local_dir './ckpt/HeartTranscriptor-oss'
```

```python
import torch
from heartlib import HeartTranscriptorPipeline

# Checkpoint directory must contain ./ckpt/HeartTranscriptor-oss/
pipe = HeartTranscriptorPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),
    dtype=torch.float16,
)
# Pipeline is configured with chunk_length_s=30, batch_size=16 internally
```
```

--------------------------------

### Load HeartMuLaGenPipeline (Single-GPU)

Source: https://context7.com/heartmula/heartlib/llms.txt

Load the music generation pipeline on a single CUDA device. Recommended dtypes are bfloat16 for HeartMuLa and float32 for HeartCodec.

```python
import torch
from heartlib import HeartMuLaGenPipeline

# --- Standard single-GPU load ---
pipe = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),          # both components on same device
    dtype={
        "mula": torch.bfloat16,           # recommended dtype for HeartMuLa
        "codec": torch.float32,           # fp32 preserves audio quality
    },
    version="3B",                         # "3B" is the only released OSS version
    lazy_load=False,
)
```

--------------------------------

### Autoregressive Single-Frame Token Generation with HeartMuLa

Source: https://context7.com/heartmula/heartlib/llms.txt

The `HeartMuLa.generate_frame` method generates one frame of 8 audio tokens autoregressively. It requires pre-setup KV-caches and uses a transformer backbone with a decoder head. CFG is supported by setting `batch_size=2`.

```python
import torch
from heartlib.heartmula.modeling_heartmula import HeartMuLa

mula = HeartMuLa.from_pretrained(
    "./ckpt/HeartMuLa-oss-3B",
    device_map=torch.device("cuda"),
    dtype=torch.bfloat16,
)

# Setup KV-caches before generation
# bs_size=2 for CFG (conditioned + unconditioned branches), 1 for greedy
mula.setup_caches(max_batch_size=2)

# tokens: [batch, seq_len, 9]  — 8 audio codebooks + 1 text channel
# tokens_mask: [batch, seq_len, 9] bool — which channels are active
batch_size = 2   # CFG requires batch=2
seq_len    = 64  # prompt length (tags + lyrics tokens)
tokens      = torch.zeros(batch_size, seq_len, 9, dtype=torch.long, device="cuda")
tokens_mask = torch.zeros(batch_size, seq_len, 9, dtype=torch.bool, device="cuda")
tokens_mask[:, :, -1] = True  # text channel active during prompt

input_pos = torch.arange(seq_len, device="cuda").unsqueeze(0).expand(batch_size, -1)
muq_embed = torch.zeros(batch_size, 512, dtype=torch.bfloat16, device="cuda")  # MuQ/MuLan embedding

with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
    frame_tokens = mula.generate_frame(
        tokens=tokens,
        tokens_mask=tokens_mask,
        input_pos=input_pos,
        temperature=1.0,
        topk=50,
        cfg_scale=1.5,
        continuous_segments=muq_embed,
        starts=[seq_len - 1] * batch_size,  # index where MuQ embedding is injected
    )

# frame_tokens: [batch, 8]  — one frame of 8 codebook indices
print(frame_tokens.shape)   # torch.Size([2, 8])
print(frame_tokens[0])      # conditioned branch tokens, e.g. tensor([412, 7031, ...])
```

--------------------------------

### Load HeartMuLaGenPipeline (Memory-Saving Lazy Load)

Source: https://context7.com/heartmula/heartlib/llms.txt

Load the music generation pipeline with lazy loading enabled for single GPUs with limited VRAM. This unloads each component after its inference phase.

```python
# --- Memory-saving lazy load (single GPU with limited VRAM) ---
pipe_lazy = HeartMuLaGenPipeline.from_pretrained(
    pretrained_path="./ckpt",
    device=torch.device("cuda"),
    dtype={"mula": torch.bfloat16, "codec": torch.float32},
    version="3B",
    lazy_load=True,    # unloads each component after its inference phase
)
```

--------------------------------

### HeartMuLaGenPipeline.__call__

Source: https://context7.com/heartmula/heartlib/llms.txt

Generates music using the full pipeline, from text preprocessing to audio decoding and saving the output as an MP3 file.

```APIDOC
## HeartMuLaGenPipeline.__call__

### Description
Runs the full generation pipeline: preprocesses text inputs → autoregressive token generation with CFG → audio decoding → saves MP3 to disk.

### Method
`pipe(lyrics: str, tags: str, output_path: str, **kwargs)`

### Parameters
#### Input Lyrics
- **lyrics** (str) - Required - The lyrics for the music generation.

#### Style Tags
- **tags** (str) - Required - Tags to influence the style of the generated music.

#### Output Path
- **output_path** (str) - Required - The file path where the generated MP3 will be saved.

#### Additional Arguments
- **kwargs** - Optional - Additional keyword arguments to pass to the underlying generation models.

### Request Example
```python
import torch
from heartlib import HeartMuLaGenPipeline

pipe = HeartMuLaGenPipeline.from_pretrained(
    "./ckpt",
    device=torch.device("cuda"),
    dtype={"mula": torch.bfloat16, "codec": torch.float32},
    version="3B",
)

pipe(
    lyrics="This is a happy song.",
    tags="pop, upbeat",
    output_path="./output.mp3"
)
```
```

--------------------------------

### Decode Audio Tokens to Waveform with HeartCodec

Source: https://context7.com/heartmula/heartlib/llms.txt

Use `HeartCodec.detokenize` to convert discrete audio codes into a 48 kHz audio waveform. Adjust `num_steps` for quality and `guidance_scale` for CFG. The `duration` parameter specifies the internal processing window.

```python
import torch
from heartlib.heartcodec.modeling_heartcodec import HeartCodec

codec = HeartCodec.from_pretrained(
    "./ckpt/HeartCodec-oss",
    device_map=torch.device("cuda"),
    dtype=torch.float32,
)

# codes: shape [num_quantizers=8, T_frames]  (T_frames at 12.5 Hz)
# For a 10-second clip: T_frames ≈ 125
codes = torch.randint(0, 8192, (8, 125), device="cuda")

with torch.inference_mode():
    wav = codec.detokenize(
        codes,
        duration=29.76,        # segment duration in seconds (internal processing window)
        num_steps=10,          # flow-matching ODE solver steps (higher = better quality)
        disable_progress=False,
        guidance_scale=1.25,   # CFG scale for the flow-matching decoder
    )

# wav: shape [2, N_samples] at 48000 Hz
import torchaudio
torchaudio.save("decoded.mp3", wav.to(torch.float32).cpu(), 48000)
print(f"Decoded waveform shape: {wav.shape}")  # e.g. torch.Size([2, 480000]) for 10s
```

--------------------------------

### HeartTranscriptorPipeline.__call__

Source: https://context7.com/heartmula/heartlib/llms.txt

Runs chunked Whisper-style ASR on any audio file. Best results are obtained on **separated vocal tracks** (e.g. pre-processed with `demucs`).

```APIDOC
## HeartTranscriptorPipeline.__call__ — Transcribe lyrics from an audio file

Runs chunked Whisper-style ASR on any audio file. Best results are obtained on **separated vocal tracks** (e.g. pre-processed with `demucs`).

```python
import torch
from heartlib import HeartTranscriptorPipeline

pipe = HeartTranscriptorPipeline.from_pretrained(
    "./ckpt",
    device=torch.device("cuda"),
    dtype=torch.float16,
)
```
```

--------------------------------

### HeartMula Citation

Source: https://github.com/heartmula/heartlib/blob/main/README.md

This is the citation information for the HeartMuLa: A Family of Open Sourced Music Foundation Models paper.

```bibtex
@misc{yang2026heartmulafamilyopensourced,
      title={HeartMuLa: A Family of Open Sourced Music Foundation Models},
      author={Dongchao Yang and Yuxin Xie and Yuguo Yin and Zheyu Wang and Xiaoyu Yi and Gongxi Zhu and Xiaolong Weng and Zihan Xiong and Yingzhe Ma and Dading Cong and Jingliang Liu and Zihang Huang and Jinghan Ru and Rongjie Huang and Haoran Wan and Peixu Wang and Kuoxi Yu and Helin Wang and Liming Liang and Xianwei Zhuang and Yuanyuan Wang and Haohan Guo and Junjie Cao and Zeqian Ju and Songxiang Liu and Yuewen Cao and Heming Weng and Yuexian Zou},
      year={2026},
      eprint={2601.10547},
      archivePrefix={arXiv},
      primaryClass={cs.SD},
      url={https://arxiv.org/abs/2601.10547},
}
```

--------------------------------

### Transcribe Lyrics from Audio

Source: https://context7.com/heartmula/heartlib/llms.txt

Transcribe lyrics from an audio file using the loaded HeartTranscriptor pipeline. Best results are achieved with pre-separated vocal tracks.

```python
import torch
from heartlib import HeartTranscriptorPipeline

pipe = HeartTranscriptorPipeline.from_pretrained(
    "./ckpt",
    device=torch.device("cuda"),
    dtype=torch.float16,
)
```

--------------------------------

### HeartMuLaGenConfig for Generation Parameters

Source: https://context7.com/heartmula/heartlib/llms.txt

The `HeartMuLaGenConfig` dataclass stores special token IDs and structural constants for inference. It can be loaded from a `gen_config.json` file or constructed manually for custom configurations.

```python
from heartlib.pipelines.music_generation import HeartMuLaGenConfig

# Load from checkpoint directory
config = HeartMuLaGenConfig.from_file("./ckpt/gen_config.json")

print(config.text_bos_id)   # e.g. 128000  — text begin-of-sequence token
print(config.text_eos_id)   # e.g. 128001  — text end-of-sequence token
print(config.audio_eos_id)  # e.g. 8193    — audio end-of-sequence token (stops generation)
print(config.empty_id)      # e.g. 0       — padding token for audio channels

# Or construct manually for custom setups
custom_config = HeartMuLaGenConfig(
    text_bos_id=128000,
    text_eos_id=128001,
    audio_eos_id=8193,
    empty_id=0,
)
```

--------------------------------

### Transcribe Audio

Source: https://context7.com/heartmula/heartlib/llms.txt

Transcribes an audio file to text using a pre-trained model. Supports various generation parameters for fine-tuning the transcription process.

```APIDOC
## Transcribe Audio

### Description
Transcribes an audio file to text using a pre-trained model. Supports various generation parameters for fine-tuning the transcription process.

### Usage
```python
from transformers import pipeline

pipe = pipeline(
    "automatic-speech-recognition",
    model="path/to/your/model"
)

result = pipe(
    "./assets/output.mp3",
    **{
        "max_new_tokens": 256,
        "num_beams": 2,
        "task": "transcribe",
        "condition_on_prev_tokens": False,
        "compression_ratio_threshold": 1.8,
        "temperature": (0.0, 0.1, 0.2, 0.4),
        "logprob_threshold": -1.0,
        "no_speech_threshold": 0.4,
    },
)

print(result)
# Example output: {'text': ' The sun creeps in across the floor I hear the traffic outside the door...'}
```

### CLI Equivalent
```bash
python ./examples/run_lyrics_transcription.py \
    --model_path=./ckpt \
    --music_path=./assets/output.mp3
```

### Note on Accuracy
For best accuracy, separate vocals from the mix first using demucs:
```bash
pip install demucs
python -m demucs --two-stems=vocals ./assets/output.mp3
# then transcribe separated/htdemucs/output/vocals.wav
```
```

--------------------------------

### HeartMuLaGenConfig

Source: https://context7.com/heartmula/heartlib/llms.txt

Dataclass for generation configuration, holding special token IDs and constants.

```APIDOC
## `HeartMuLaGenConfig` — Generation configuration dataclass

### Description
Holds special token IDs and structural constants used during inference. Loaded automatically from `gen_config.json` in the checkpoint directory.

### Usage
```python
from heartlib.pipelines.music_generation import HeartMuLaGenConfig

# Load from checkpoint directory
config = HeartMuLaGenConfig.from_file("./ckpt/gen_config.json")

print(config.text_bos_id)   # e.g. 128000  — text begin-of-sequence token
print(config.text_eos_id)   # e.g. 128001  — text end-of-sequence token
print(config.audio_eos_id)  # e.g. 8193    — audio end-of-sequence token (stops generation)
print(config.empty_id)      # e.g. 0       — padding token for audio channels

# Or construct manually for custom setups
custom_config = HeartMuLaGenConfig(
    text_bos_id=128000,
    text_eos_id=128001,
    audio_eos_id=8193,
    empty_id=0,
)
```
```

--------------------------------

### HeartMuLa.generate_frame

Source: https://context7.com/heartmula/heartlib/llms.txt

Generates a single frame of audio tokens autoregressively.

```APIDOC
## `HeartMuLa.generate_frame` — Autoregressive single-frame token generation (low-level)

### Description
Core autoregressive step that generates one frame of 8 audio codebook tokens given a context of prior tokens. Uses a backbone LLaMA-3B transformer plus a lightweight decoder head with CFG support.

### Method Signature
```python
generate_frame(tokens, tokens_mask, input_pos, temperature, topk, cfg_scale, continuous_segments, starts)
```

### Parameters
- **tokens** (`torch.Tensor`) - Shape `[batch, seq_len, 9]` containing 8 audio codebooks + 1 text channel.
- **tokens_mask** (`torch.Tensor`) - Shape `[batch, seq_len, 9]` boolean mask indicating active channels.
- **input_pos** (`torch.Tensor`) - Input positions for the transformer.
- **temperature** (`float`) - Sampling temperature.
- **topk** (`int`) - Top-k sampling parameter.
- **cfg_scale** (`float`) - Classifier-Free Guidance scale.
- **continuous_segments** (`torch.Tensor`) - MuQ/MuLan embedding for continuous segments.
- **starts** (`list[int]`) - List of indices where MuQ embedding is injected.

### Request Example
```python
import torch
from heartlib.heartmula.modeling_heartmula import HeartMuLa

mula = HeartMuLa.from_pretrained(
    "./ckpt/HeartMuLa-oss-3B",
    device_map=torch.device("cuda"),
    dtype=torch.bfloat16,
)

# Setup KV-caches before generation
# bs_size=2 for CFG (conditioned + unconditioned branches), 1 for greedy
mula.setup_caches(max_batch_size=2)

# tokens: [batch, seq_len, 9]  — 8 audio codebooks + 1 text channel
# tokens_mask: [batch, seq_len, 9] bool — which channels are active
batch_size = 2   # CFG requires batch=2
seq_len    = 64  # prompt length (tags + lyrics tokens)
tokens      = torch.zeros(batch_size, seq_len, 9, dtype=torch.long, device="cuda")
tokens_mask = torch.zeros(batch_size, seq_len, 9, dtype=torch.bool, device="cuda")
tokens_mask[:, :, -1] = True  # text channel active during prompt

input_pos = torch.arange(seq_len, device="cuda").unsqueeze(0).expand(batch_size, -1)
muq_embed = torch.zeros(batch_size, 512, dtype=torch.bfloat16, device="cuda")  # MuQ/MuLan embedding

with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
    frame_tokens = mula.generate_frame(
        tokens=tokens,
        tokens_mask=tokens_mask,
        input_pos=input_pos,
        temperature=1.0,
        topk=50,
        cfg_scale=1.5,
        continuous_segments=muq_embed,
        starts=[seq_len - 1] * batch_size,  # index where MuQ embedding is injected
    )

# frame_tokens: [batch, 8]  — one frame of 8 codebook indices
print(frame_tokens.shape)   # torch.Size([2, 8])
print(frame_tokens[0])      # conditioned branch tokens, e.g. tensor([412, 7031, ...])
```
```

--------------------------------

### HeartCodec.detokenize

Source: https://context7.com/heartmula/heartlib/llms.txt

Decodes audio token codes back to a waveform using flow-matching diffusion.

```APIDOC
## `HeartCodec.detokenize` — Decode audio token codes to a waveform

### Description
Low-level method on the `HeartCodec` model that converts an `[8, T]` tensor of discrete audio codes back to a 48 kHz audio waveform tensor using flow-matching diffusion.

### Method Signature
```python
detokenize(codes, duration, num_steps, disable_progress, guidance_scale)
```

### Parameters
- **codes** (`torch.Tensor`) - Shape `[num_quantizers=8, T_frames]` discrete audio codes.
- **duration** (`float`) - Segment duration in seconds (internal processing window).
- **num_steps** (`int`) - Flow-matching ODE solver steps (higher = better quality).
- **disable_progress** (`bool`) - Whether to disable the progress bar.
- **guidance_scale** (`float`) - CFG scale for the flow-matching decoder.

### Request Example
```python
import torch
import torchaudio
from heartlib.heartcodec.modeling_heartcodec import HeartCodec

codec = HeartCodec.from_pretrained(
    "./ckpt/HeartCodec-oss",
    device_map=torch.device("cuda"),
    dtype=torch.float32,
)

# codes: shape [num_quantizers=8, T_frames]  (T_frames at 12.5 Hz)
# For a 10-second clip: T_frames ≈ 125
codes = torch.randint(0, 8192, (8, 125), device="cuda")

with torch.inference_mode():
    wav = codec.detokenize(
        codes,
        duration=29.76,        # segment duration in seconds (internal processing window)
        num_steps=10,          # flow-matching ODE solver steps (higher = better quality)
        disable_progress=False,
        guidance_scale=1.25,   # CFG scale for the flow-matching decoder
    )

# wav: shape [2, N_samples] at 48000 Hz
torchaudio.save("decoded.mp3", wav.to(torch.float32).cpu(), 48000)
print(f"Decoded waveform shape: {wav.shape}")  # e.g. torch.Size([2, 480000]) for 10s
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.