# lrc-gen

**Repository Path**: jori-wang/lrc-gen

## Basic Information

- **Project Name**: lrc-gen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# AI-Based LRC Lyrics Generator (基于大模型的歌词生成器)

这是一个基于 **LangGraph** 和 **多模态大模型** 的命令行工具，旨在自动化为 MP3 文件生成带精确时间轴的 LRC 滚动歌词。

它利用 Google Gemini 3 的原生听觉能力生成时间轴，并使用 Qwen 模型进行文本校对，最后通过 LangGraph 编排完整的工作流。

## 🚀 核心功能

* **智能文件名解析**：自动识别文件名中的“歌手”和“歌名”。支持无规律文件名处理（自动降级为仅歌名模式）。
* **多模态歌词生成**：直接将音频数据（Base64）传输给 `google/gemini-3-flash-preview`，一步生成带 `[mm:ss.xx]` 时间戳的 LRC 内容。
* **智能质检**：使用 `qwen/qwen3-235b` 对生成结果进行错别字和语病修正，严格保持时间轴不偏移。
* **自动化工作流**：基于 LangGraph 1.x 构建的状态机，确保流程可控、可扩展。

## 🛠 技术栈

* **语言**: Python 3.12+
* **核心框架**: [LangGraph](https://langchain-ai.github.io/langgraph/), [LangChain](https://www.langchain.com/)
* **API 接入**: OpenRouter API
* **模型**:
    * 音频理解 & 生成: `google/gemini-3-flash-preview`
    * 文本解析 & 校验: `qwen/qwen3-235b-a22b-2507`
* **CLI 工具**: Typer

## 📋 前置要求

* Ubuntu 22.04 (推荐) / macOS / Windows
* [uv](https://docs.astral.sh/uv/) (推荐) 或 Python 3.12+
* **OpenRouter API Key** (需有额度)

## 📦 安装指南

### 1. 安装 uv (如果尚未安装)

请参考 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/)。

### 2. 初始化环境与安装依赖

在项目根目录下运行：

```bash
uv sync
```

这会自动创建虚拟环境并安装所有必要依赖。

### 3. 配置环境变量

在项目根目录下创建一个 `.env` 文件，填入您的 OpenRouter Key：

```ini
# .env file
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# (可选) 设置默认歌词存储目录
LRC_DST_DIR=./lyrics
```

## 🏃‍♂️ 使用方法

本工具设计为 CLI (命令行) 模式，针对单个 MP3 文件进行处理。

### 基本命令

```bash
uv run python main.py -src "/path/to/your/song.mp3"
```

### 运行示例

假设文件名为 `周杰伦 - 稻香.mp3`：

```bash
uv run python main.py -src "./music/周杰伦 - 稻香.mp3"
```

### 进阶配置：指定歌词存储路径

默认情况下，歌词保存在与 MP3 文件相同的目录下。您可以通过以下两种方式自定义存储位置：

#### 1. 使用命令行参数 (优先级最高)
```bash
uv run python main.py -src "song.mp3" -lrc-dst-dir "./my_lyrics"
```

#### 2. 使用环境变量
在 `.env` 中配置 `LRC_DST_DIR` 或在终端设置：
```bash
export LRC_DST_DIR="./lyrics"
uv run python main.py -src "song.mp3"
```

**程序运行流程：**

1. **解析**: 识别 Artist: `周杰伦`, Title: `稻香`。
2. **生成**: 上传音频至 Gemini，等待生成 LRC...
3. **校对**: Qwen 检查文本正确性。
4. **保存**: 根据配置保存 `.lrc` 文件（若指定目录不存在则自动创建）。

## 🧩 工作流架构 (LangGraph)

系统内部通过以下状态节点流转：

```mermaid
graph LR
    A[Start] --> B(parse_filename_node)
    B --> C(generate_lrc_node)
    C --> D(validate_lrc_node)
    D --> E(save_file_node)
    E --> F[End]

```

1. **parse_filename**: 提取元数据，若无连字符则仅提取 Title。
2. **generate_lrc**: 音频转 Base64 -> 多模态 LLM -> 原始 LRC。
3. **validate_lrc**: 锁定时间轴，仅修正文本内容。
4. **save_file**: 写入磁盘。

## ⚠️ 注意事项

1. **文件大小**: 由于需要将 MP3 转为 Base64 传入上下文，建议 MP3 文件不要过大（建议 < 10MB）。对于无损 FLAC 或超长音频，建议先转码为标准 MP3。
2. **API 成本**: 多模态音频输入会消耗较多 Token，请关注 OpenRouter 额度使用情况。
3. **网络**: 请确保开发环境可以连接到 OpenRouter API 节点。