audiocraft-audio-generation

AudioCraft：音频生成

使用 Meta 的 AudioCraft，通过 MusicGen、AudioGen 和 EnCodec 进行文本转音乐和文本转音频生成的综合指南。

何时使用 AudioCraft

在以下情况下使用 AudioCraft：

• 需要根据文本描述生成音乐
• 创建音效和环境音频
• 构建音乐生成应用
• 需要以旋律为条件生成音乐
• 希望输出立体声音频
• 需要通过风格迁移实现可控的音乐生成

主要功能：

• MusicGen：支持旋律条件的文本转音乐生成
• AudioGen：文本转音效生成
• EnCodec：高保真神经音频编解码器
• 多种模型规模：从 Small（300M）到 Large（3.3B）
• 立体声支持：完整的立体声音频生成
• 风格条件：MusicGen-Style 支持基于参考内容生成

改用以下替代方案：

• Stable Audio：适用于生成更长的商业音乐
• Bark：适用于文本转语音以及音乐/音效生成
• Riffusion：适用于基于频谱图的音乐生成
• OpenAI Jukebox：适用于生成带歌词的原始音频

快速开始

安装

# From PyPI
pip install audiocraft

# From GitHub (latest)
pip install git+https://github.com/facebookresearch/audiocraft.git

# Or use HuggingFace Transformers
pip install transformers torch torchaudio

基本文本转音乐（AudioCraft）

import torchaudio
from audiocraft.models import MusicGen

# Load model
model = MusicGen.get_pretrained('facebook/musicgen-small')

# Set generation parameters
model.set_generation_params(
    duration=8,  # seconds
    top_k=250,
    temperature=1.0
)

# Generate from text
descriptions = ["happy upbeat electronic dance music with synths"]
wav = model.generate(descriptions)

# Save audio
torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)

使用 HuggingFace Transformers

from transformers import AutoProcessor, MusicgenForConditionalGeneration
import scipy

# Load model and processor
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
model.to("cuda")

# Generate music
inputs = processor(
    text=["80s pop track with bassy drums and synth"],
    padding=True,
    return_tensors="pt"
).to("cuda")

audio_values = model.generate(
    **inputs,
    do_sample=True,
    guidance_scale=3,
    max_new_tokens=256
)

# Save
sampling_rate = model.config.audio_encoder.sampling_rate
scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())

使用 AudioGen 进行文本转音效

from audiocraft.models import AudioGen

# Load AudioGen
model = AudioGen.get_pretrained('facebook/audiogen-medium')

model.set_generation_params(duration=5)

# Generate sound effects
descriptions = ["dog barking in a park with birds chirping"]
wav = model.generate(descriptions)

torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)

核心概念

架构概览

AudioCraft Architecture:
┌──────────────────────────────────────────────────────────────┐
│                    Text Encoder (T5)                          │
│                         │                                     │
│                    Text Embeddings                            │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│              Transformer Decoder (LM)                         │
│     Auto-regressively generates audio tokens                  │
│     Using efficient token interleaving patterns               │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                EnCodec Audio Decoder                          │
│        Converts tokens back to audio waveform                 │
└──────────────────────────────────────────────────────────────┘

模型变体

模型	规模	描述	用途
musicgen-small	300M	文本转音乐	快速生成
musicgen-medium	1.5B	文本转音乐	均衡表现
musicgen-large	3.3B	文本转音乐	最佳质量
musicgen-melody	1.5B	文本 + 旋律	旋律条件
musicgen-melody-large	3.3B	文本 + 旋律	最佳旋律效果
musicgen-stereo-*	不定	立体声输出	立体声生成
musicgen-style	1.5B	风格迁移	基于参考内容生成
audiogen-medium	1.5B	文本转音效	音效

生成参数

参数	默认值	描述
duration	8.0	时长（秒，1-120）
top_k	250	Top-k 采样
top_p	0.0	核采样（0 = 禁用）
temperature	1.0	采样温度
cfg_coef	3.0	无分类器引导

MusicGen 用法

详情、代码示例和参数表：references/musicgen-usage.md。在适用此步骤时阅读。

MusicGen-Style 用法

详情、代码示例和参数表：references/musicgen-style-usage.md。在适用此步骤时阅读。

AudioGen 用法

音效生成

from audiocraft.models import AudioGen
import torchaudio

model = AudioGen.get_pretrained('facebook/audiogen-medium')
model.set_generation_params(duration=10)

# Generate various sounds
descriptions = [
    "thunderstorm with heavy rain and lightning",
    "busy city traffic with car horns",
    "ocean waves crashing on rocks",
    "crackling campfire in forest"
]

wav = model.generate(descriptions)

for i, audio in enumerate(wav):
    torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)

EnCodec 用法

音频压缩

from audiocraft.models import CompressionModel
import torch
import torchaudio

# Load EnCodec
model = CompressionModel.get_pretrained('facebook/encodec_32khz')

# Load audio
wav, sr = torchaudio.load("audio.wav")

# Ensure correct sample rate
if sr != 32000:
    resampler = torchaudio.transforms.Resample(sr, 32000)
    wav = resampler(wav)

# Encode to tokens
with torch.no_grad():
    encoded = model.encode(wav.unsqueeze(0))
    codes = encoded[0]  # Audio codes

# Decode back to audio
with torch.no_grad():
    decoded = model.decode(codes)

torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)

常见工作流

工作流 1：音乐生成流程

import torch
import torchaudio
from audiocraft.models import MusicGen

class MusicGenerator:
    def __init__(self, model_name="facebook/musicgen-medium"):
        self.model = MusicGen.get_pretrained(model_name)
        self.sample_rate = 32000

    def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):
        self.model.set_generation_params(
            duration=duration,
            top_k=250,
            temperature=temperature,
            cfg_coef=cfg
        )

        with torch.no_grad():
            wav = self.model.generate([prompt])

        return wav[0].cpu()

    def generate_batch(self, prompts, duration=30):
        self.model.set_generation_params(duration=duration)

        with torch.no_grad():
            wav = self.model.generate(prompts)

        return wav.cpu()

    def save(self, audio, path):
        torchaudio.save(path, audio, sample_rate=self.sample_rate)

# Usage
generator = MusicGenerator()
audio = generator.generate(
    "epic cinematic orchestral music",
    duration=30,
    temperature=1.0
)
generator.save(audio, "epic_music.wav")

工作流 2：音效设计批处理

import json
from pathlib import Path
from audiocraft.models import AudioGen
import torchaudio

def batch_generate_sounds(sound_specs, output_dir):
    """
    Generate multiple sounds from specifications.

    Args:
        sound_specs: list of {"name": str, "description": str, "duration": float}
        output_dir: output directory path
    """
    model = AudioGen.get_pretrained('facebook/audiogen-medium')
    output_dir = Path(output_dir)
    output_dir.mkdir(exist_ok=True)

    results = []

    for spec in sound_specs:
        model.set_generation_params(duration=spec.get("duration", 5))

        wav = model.generate([spec["description"]])

        output_path = output_dir / f"{spec['name']}.wav"
        torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)

        results.append({
            "name": spec["name"],
            "path": str(output_path),
            "description": spec["description"]
        })

    return results

# Usage
sounds = [
    {"name": "explosion", "description": "massive explosion with debris", "duration": 3},
    {"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},
    {"name": "door", "description": "wooden door creaking and closing", "duration": 2}
]

results = batch_generate_sounds(sounds, "sound_effects/")

工作流 3：Gradio 演示

import gradio as gr
import torch
import torchaudio
from audiocraft.models import MusicGen

model = MusicGen.get_pretrained('facebook/musicgen-small')

def generate_music(prompt, duration, temperature, cfg_coef):
    model.set_generation_params(
        duration=duration,
        temperature=temperature,
        cfg_coef=cfg_coef
    )

    with torch.no_grad():
        wav = model.generate([prompt])

    # Save to temp file
    path = "temp_output.wav"
    torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
    return path

demo = gr.Interface(
    fn=generate_music,
    inputs=[
        gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),
        gr.Slider(1, 30, value=8, label="Duration (seconds)"),
        gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),
        gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")
    ],
    outputs=gr.Audio(label="Generated Music"),
    title="MusicGen Demo"
)

demo.launch()

性能优化

内存优化

# Use smaller model
model = MusicGen.get_pretrained('facebook/musicgen-small')

# Clear cache between generations
torch.cuda.empty_cache()

# Generate shorter durations
model.set_generation_params(duration=10)  # Instead of 30

# Use half precision
model = model.half()

批处理效率

# Process multiple prompts at once (more efficient)
descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]
wav = model.generate(descriptions)  # Single batch

# Instead of
for desc in descriptions:
    wav = model.generate([desc])  # Multiple batches (slower)

GPU 显存需求

模型	FP32 显存	FP16 显存
musicgen-small	~4GB	~2GB
musicgen-medium	~8GB	~4GB
musicgen-large	~16GB	~8GB

常见问题

问题	解决方案
CUDA 显存溢出	使用更小的模型，缩短时长
质量不佳	增大 cfg_coef，改进提示词
生成内容过短	检查最大时长设置
音频伪影	尝试不同的温度
立体声无法使用	使用立体声模型变体

参考资料

• 高级用法 - 训练、微调、部署
• 故障排除 - 常见问题和解决方案

资源

• GitHub：https://github.com/facebookresearch/audiocraft
• 论文（MusicGen）：https://arxiv.org/abs/2306.05284
• 论文（AudioGen）：https://arxiv.org/abs/2209.15352
• HuggingFace：https://huggingface.co/facebook/musicgen-small
• 演示：https://huggingface.co/spaces/facebook/MusicGen

Agent 操作流程

1. 检查环境。 确认 GPU 内存、模型检查点和许可证、框架版本及输入格式。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。对于任何会改变结果的值，都应询问，不要猜测。
3. 先运行小规模版本。 先对单个样本进行推理，使用较低分辨率或较短时长。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 通过定性检查和任务指标检查输出；确认生成内容的许可证限制。
6. 报告。 说明运行内容（版本、命令、参数）、检查内容，以及仍不确定的事项。

如果出现这种情况	请这样做
大型输入导致内存不足	降低分辨率或序列长度、使用半精度，或对输入进行分块。
这些说明中提及的函数、标志或端点在已安装的版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整，并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信准则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 商业使用或发布内容前，检查模型和数据集许可证。
• 请将此处与特定版本相关的详细信息视为可能已过时：根据已安装版本的官方文档进行确认。
• 对于需要花钱、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• transformers：用于加载 Hub 模型、运行 pipeline 推理、文本生成，以及在 NLP、视觉、音频等领域使用 Trainer 进行微调的 Hugging Face Transformers。