leshicodes/lrclib-fetcher

LRCLib Fetcher

镜像概述

LRCLib Fetcher是一个TypeScript库和CLI工具，用于从LRCLib.net获取音乐文件的同步歌词，支持批量处理、元数据提取、智能搜索等多种功能，可通过Docker便捷部署，满足本地音乐库或音乐应用的歌词获取需求。

核心功能

• 批量处理：并行处理多个音乐文件，可配置批处理大小
• 元数据提取：自动从音频文件元数据中提取艺术家和标题信息
• 同步歌词优先：优先获取带时间戳的同步.lrc文件
• 智能搜索：采用多种 fallback 策略确保找到最佳匹配歌词
• 文件管理：支持跳过已有歌词或覆盖现有文件
• 详细日志：可配置日志级别（debug/info/warn/error）用于调试

使用场景

• 为本地音乐库批量添加同步歌词
• 音乐播放器配套工具，自动补全歌词
• 音乐相关应用开发时集成歌词获取功能

配置说明与Docker部署

Docker镜像拉取

bash
docker pull leshicodes/lrclib-fetcher:0.0.2

基础运行（映射音乐目录）

bash
docker run -v "/本地音乐路径:/music" leshicodes/lrclib-fetcher:0.0.2

自定义参数运行

bash
docker run -v "/本地音乐路径:/music" leshicodes/lrclib-fetcher:0.0.2 /music --overwrite --batch-size 10 --delay 2000

CLI选项说明

• -r/--recursive：递归扫描目录（默认true）
• --no-skip-existing：不跳过已有歌词文件
• -o/--overwrite：覆盖现有歌词（默认false）
• -b/--batch-size：并行处理文件数（默认5）
• -d/--delay：API请求间隔（默认1000ms）
• --log-level：日志级别（debug/info/warn/error，默认info）

程序matic使用示例

typescript
import { createLyricsFetcher } from 'lrclib-fetcher-ts';

const fetcher = createLyricsFetcher({
  logging: { level: 'info', logToFile: false },
  search: { allowTitleOnlySearch: true, preferSynced: true },
  file: { skipExisting: true, overwriteExisting: false },
  batch: { enabled: true, size:5, delayMs:1000 }
});

fetcher.processDirectory('/path/to/music')
  .then(results => console.log(`成功处理${results.filter(r=>r.success).length}/${results.length}个文件`))
  .catch(err => console.error('错误:', err));

许可证

MIT

致谢

本项目使用LRCLib.net的非官方API，歌词由LRCLib.net用户提供。