# riffusion-hobby

**Repository Path**: toolsmanhehe/riffusion-hobby

## Basic Information

- **Project Name**: riffusion-hobby
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-03
- **Last Updated**: 2025-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# :guitar: Riffusion (hobby)

:no_entry: 本项目不再积极维护。

<a href="https://github.com/riffusion/riffusion/actions/workflows/ci.yml?query=branch%3Amain"><img alt="CI状态" src="https://github.com/riffusion/riffusion/actions/workflows/ci.yml/badge.svg" /></a>
<img alt="Python 3.9 | 3.10" src="https://img.shields.io/badge/Python-3.9%20%7C%203.10-blue" />
<a href="https://github.com/riffusion/riffusion/tree/main/LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-yellowgreen" /></a>

Riffusion 是一个用于实时音乐和音频生成的扩散模型库。

了解更多请访问 https://www.riffusion.com/about 并在 https://www.riffusion.com/ 尝试使用。

这是 riffusion 图像和音频处理代码的核心仓库。

* 执行提示插值结合图像条件的扩散管道
* 频谱图图像与音频剪辑之间的转换
* 常见任务的命令行接口
* 使用 streamlit 的交互式应用
* 通过 API 提供模型推理的 Flask 服务器
* 各种第三方集成

相关仓库：
* Web 应用: https://github.com/riffusion/riffusion-app
* 模型检查点: https://huggingface.co/riffusion/riffusion-model-v1

## 引用

如果您在此工作基础上进行构建，请引用如下：

```
@article{Forsgren_Martiros_2022,
  author = {Forsgren, Seth* and Martiros, Hayk*},
  title = {{Riffusion - Stable diffusion for real-time music generation}},
  url = {https://riffusion.com/about},
  year = {2022}
}
```

## 安装

在 CI 中测试过使用 Python 3.9 和 3.10。

强烈建议使用 `conda` 或 `virtualenv` 设置虚拟 Python 环境：
```
conda create --name riffusion python=3.9
conda activate riffusion
```

安装 Python 依赖：
```
python -m pip install -r requirements.txt
```

为了使用除 WAV 以外的音频格式，需要安装 [ffmpeg](https://ffmpeg.org/download.html)：
```
sudo apt-get install ffmpeg          # Linux
brew install ffmpeg                  # Mac
conda install -c conda-forge ffmpeg  # Conda
```

如果 torchaudio 没有后端，您可能需要安装 `libsndfile`。请参阅 [此问题](https://github.com/riffusion/riffusion/issues/12)。

如果您遇到问题，请尝试升级 [diffusers](https://github.com/huggingface/diffusers)。测试过使用 0.9 - 0.11。

指南：
* [Windows 简单安装指南](https://www.reddit.com/r/riffusion/comments/zrubc9/installation_guide_for_riffusion_app_inference/)

## 后端

### CPU
`cpu` 是支持的，但速度相当慢。

### CUDA
`cuda` 是推荐且性能最佳的后端。

要使用 CUDA，请确保安装了带有 CUDA 支持的 torch 和 torchaudio。请参阅 [安装指南](https://pytorch.org/get-started/locally/) 或 [稳定版本](https://download.pytorch.org/whl/torch_stable.html)。

要实时生成音频，您需要一个能够在大约 50 步内运行稳定扩散的 GPU，如 3090 或 A10G。

测试可用性：
```python3
import torch
torch.cuda.is_available()
```

### MPS
Apple Silicon 上的 `mps` 后端支持推理，但某些操作会回退到 CPU，特别是音频处理。您可能需要设置 `PYTORCH_ENABLE_MPS_FALLBACK=1`。

此外，此后端不是确定性的。

测试可用性：
```python3
import torch
torch.backends.mps.is_available()
```

## 命令行接口

Riffusion 带有一个命令行接口，用于执行常见任务。

查看可用命令：
```
python -m riffusion.cli -h
```

获取特定命令的帮助：
```
python -m riffusion.cli image-to-audio -h
```

执行：
```
python -m riffusion.cli image-to-audio --image spectrogram_image.png --audio clip.wav
```

## Riffusion Playground

Riffusion 包含一个 [streamlit](https://streamlit.io/) 应用，用于交互式使用和探索。

运行：
```
python -m riffusion.streamlit.playground
```

并通过 http://127.0.0.1:8501/ 访问。

<img alt="Riffusion Playground" style="width: 600px" src="https://i.imgur.com/OOMKBbT.png" />

## 运行模型服务器

Riffusion 可以作为 Flask 服务器运行，通过 API 提供推理。此服务器使 [Web 应用](https://github.com/riffusion/riffusion-app) 能够在本地运行。

运行：
```
python -m riffusion.server --host 127.0.0.1 --port 3013
```

您可以使用 `--checkpoint` 指定自己的目录或 diffusers 格式的 HuggingFace ID。

使用 `--device` 参数指定要使用的 torch 设备。

模型端点现在可通过 `http://127.0.0.1:3013/run_inference` 的 POST 请求访问。

示例输入（请参阅 [InferenceInput](https://github.com/hmartiro/riffusion-inference/blob/main/riffusion/datatypes.py#L28) 了解 API）：
```
{
  "alpha": 0.75,
  "num_inference_steps": 50,
  "seed_image_id": "og_beat",

  "start": {
    "prompt": "教堂钟声在星期日",
    "seed": 42,
    "denoising": 0.75,
    "guidance": 7.0
  },

  "end": {
    "prompt": "爵士钢琴",
    "seed": 123,
    "denoising": 0.75,
    "guidance": 7.0
  }
}
```

示例输出（请参阅 [InferenceOutput](https://github.com/hmartiro/riffusion-inference/blob/main/riffusion/datatypes.py#L54) 了解 API）：
```
{
  "image": "< base64 编码的 JPEG 图像 >",
  "audio": "< base64 编码的 MP3 剪辑 >"
}
```

## 测试
测试位于 `test/` 目录中，使用 `unittest` 实现。

运行所有测试：
```
python -m unittest test/*_test.py
```

运行单个测试：
```
python -m unittest test.audio_to_image_test
```

要保留临时输出进行调试，请设置 `RIFFUSION_TEST_DEBUG`：
```
RIFFUSION_TEST_DEBUG=1 python -m unittest test.audio_to_image_test
```

在特定 torch 设备上运行测试，请设置 `RIFFUSION_TEST_DEVICE`。测试应在 `cpu`、`cuda` 和 `mps` 后端下通过。

## 开发指南
安装额外的开发包，请使用 `python -m pip install -r requirements_dev.txt`。

* Linter: `ruff`
* 格式化器: `black`
* 类型检查器: `mypy`

这些在 `pyproject.toml` 中配置。

`mypy .`、`black .` 和 `ruff .` 的结果必须干净才能接受 PR。

CI 通过 GitHub Actions 从 `.github/workflows/ci.yml` 运行。

欢迎通过 pull requests 进行贡献。