#+TITLE: YTM - YouTube Music 下载器
#+AUTHOR: Cytrogen
#+DESCRIPTION: 从 YouTube Music 搜索并下载音乐的命令行工具

* 概述

YTM 是一个命令行交互式工具，用于从 YouTube Music 搜索、浏览并下载音乐到本地 Navidrome 音乐库。通过 YouTube Music InnerTube API 实现搜索和元数据解析，调用 =yt-dlp= 执行实际音频下载。

* 功能

- 通过 InnerTube API 按艺术家或专辑搜索
- 浏览艺术家的完整发行列表并选择下载
- 自动提取最高音质音频
- 嵌入封面和元数据
- 按可配置的分类文件夹整理下载内容
- 单曲自动放入 =Singles/= 子文件夹
- 基于 TOML 的配置文件

* 依赖

- Go 1.25+（用于构建）
- [[https://github.com/yt-dlp/yt-dlp][yt-dlp]] 已安装并在 PATH 中可用（或通过 =config.toml= 配置路径）

* 构建

#+begin_src bash
cd ytm
go build -o ytm.exe .
#+end_src

* 使用

#+begin_src bash
./ytm
#+end_src

** 交互命令

| 输入     | 操作                       |
|----------+----------------------------|
| =help=   | 显示帮助信息               |
| =q=      | 退出程序                   |
| 数字     | 选择单项（如 =1=）         |
| 逗号分隔 | 选择多项（如 =1,3,5=）     |
| =all=    | 选择全部                   |
| 回车     | 接受默认值                 |

** 工作流程

1. 输入搜索关键词
2. 选择搜索模式（艺术家/专辑）
3. 从结果列表中选择要下载的项目
4. 选择音乐分类和文件夹名
5. 等待下载完成

* 配置

首次运行时，会在可执行文件所在目录自动生成 =config.toml= 配置文件：

#+begin_src toml
# YTM 配置文件

# 音乐下载根目录
music_root = "D:/Music/"

# 音乐分类（对应根目录下的子文件夹）
categories = ["C-Rock", "J-Pop", "K-Pop", "Other", "Game Music"]

# yt-dlp 可执行文件路径
ytdlp_path = "yt-dlp"

# HTTP 请求超时（秒）
http_timeout = 30

# 搜索结果最大数量
max_artist_results = 8
max_album_results = 10
#+end_src

| 键                   | 说明                     | 默认值           |
|----------------------+--------------------------+------------------|
| =music_root=         | 音乐下载根目录           | =D:/Music/=      |
| =categories=         | 根目录下的分类子文件夹   | 5 个预设分类     |
| =ytdlp_path=         | yt-dlp 可执行文件路径    | =yt-dlp=         |
| =http_timeout=       | HTTP 请求超时（秒）      | =30=             |
| =max_artist_results= | 搜索返回的最大艺术家数量 | =8=              |
| =max_album_results=  | 搜索返回的最大专辑数量   | =10=             |

* 目录结构

下载内容按以下结构整理：

#+begin_example
{music_root}/
├── C-Rock/
│   └── {艺术家}/
│       ├── {专辑}/
│       │   ├── 01. 曲目一.opus
│       │   └── 02. 曲目二.opus
│       └── Singles/
│           └── 单曲.opus
├── J-Pop/
├── K-Pop/
├── Other/
└── Game Music/
#+end_example

* 项目结构

#+begin_example
ytm/
├── go.mod
├── go.sum
├── config.toml      # 首次运行时自动生成
├── config.go        # 配置加载
├── types.go         # 数据类型与常量
├── innertube.go     # YouTube Music InnerTube API 客户端
├── ytdlp.go         # yt-dlp 封装
└── main.go          # 入口与交互主循环
#+end_example