# spotify-python

**Repository Path**: cnull_project/spotify-python

## Basic Information

- **Project Name**: spotify-python
- **Description**: 1232132131312
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spotify 曲目信息查询工具

这个项目用于按歌曲名搜索 Spotify，并在命中曲目后继续查询 MusicBrainz，最终返回统一的 JSON 结果。

当前运行时中也会一并打包 `ShazamIO`，方便后续在同一个 `python-runtime` 里继续扩展音频识别相关能力。

当前项目支持两种交付方式：

- 直接使用已经打包好的 `python-runtime`
- 在新机器上重新构建 `python-runtime`

当前推荐的对外交付方式是第二种：在目标机器上运行平台对应的构建脚本，自动生成当前平台可运行的 `python-runtime`。

## 当前目录说明

主要文件如下：

- `spotify_track_lookup.py`
  业务主逻辑，负责 Spotify 搜索、Spotify 页面解析、MusicBrainz 查询、结果组装。

- `spotify_lookup_worker.py`
  命令行入口层。运行时优先加载同目录下已经编译好的扩展模块；如果没有扩展模块，则回退到源码模块。

- `build_runtime_win.bat`
  Windows 一键构建脚本。

- `build_runtime_mac.sh`
  macOS 一键构建脚本。

- `build_runtime_artifacts.py`
  共用构建脚本，负责把 `spotify_track_lookup.py` 和 `spotify_lookup_worker.py` 编译成平台相关扩展模块。

- `prune_runtime.py`
  运行时裁剪脚本，负责删除构建期依赖、缓存、调试文件和非必要目录，减小最终体积。

- `runtime-requirements.txt`
  运行时需要保留的 Python 依赖清单，当前已包含 `ShazamIO` 所需的运行依赖。

- `python-runtime/`
  构建完成后输出的本地运行时目录。Windows 下包含 `python.exe`，macOS 下包含 `bin/python`。

## 当前返回格式

当前脚本和 worker 返回的 JSON 结构如下：

```json
{
  "query": {
    "song": "月球上的人",
    "artist": "陳奕迅"
  },
  "track": {
    "name": "月球上的人",
    "spotify_url": "https://open.spotify.com/track/574qMhKU1uVxIMYotuUISk",
    "spotify_id": "574qMhKU1uVxIMYotuUISk",
    "track_number": 19,
    "album_total_tracks": 27,
    "isrc": "HKUM70700016",
    "composer": [
      "蘇耀宗"
    ],
    "album": {
      "name": "Solidays",
      "spotify_url": "https://open.spotify.com/album/0ft6r4NSMBIqZ51zbX0AfX",
      "spotify_id": "0ft6r4NSMBIqZ51zbX0AfX",
      "uri": "spotify:album:0ft6r4NSMBIqZ51zbX0AfX",
      "total_tracks": 27,
      "label": "Cinepoly Records",
      "artists": [
        {
          "name": "Eason Chan",
          "spotify_url": "https://open.spotify.com/artist/2QcZxAgcs2I1q7CtCkl6MI",
          "spotify_id": "2QcZxAgcs2I1q7CtCkl6MI"
        }
      ],
      "image_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2738714d9e2e789962fc0ad36d7"
    },
    "artists": [
      {
        "name": "Eason Chan",
        "spotify_url": "https://open.spotify.com/artist/2QcZxAgcs2I1q7CtCkl6MI",
        "spotify_id": "2QcZxAgcs2I1q7CtCkl6MI",
        "uri": "spotify:artist:2QcZxAgcs2I1q7CtCkl6MI",
        "is_verified": null,
        "genres": [
          "cantopop",
          "pop",
          "hk-pop"
        ],
        "image_url": "https://image-cdn-ak.spotifycdn.com/image/ab6761610000e5eb438e5730e9e86121f329d2dd"
      }
    ],
    "release_date": "2008-09-04",
    "genres": [
      "cantopop",
      "pop",
      "hk-pop"
    ],
    "cover_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2732e14f9afc8bc329b738554ea"
  }
}
```

## 数据来源说明

当前字段来源大致如下：

- Spotify 主来源：
  - `track.name`
  - `track.spotify_url`
  - `track.spotify_id`
  - `track.track_number`
  - `track.album_total_tracks`
  - `track.release_date`
  - `track.album.*` 中除 `label` 之外的大部分字段
  - `track.artists[*]` 中的大部分字段
  - `track.cover_url`

- MusicBrainz 主来源：
  - `track.isrc`
  - `track.composer`
  - `track.album.label`

- iTunes 补充来源：
  - 当 Spotify 公开页面无法稳定提供流派时，`genres` 可能使用 iTunes artist genre 补充。

## Windows 安装与构建流程

下面的步骤适用于全新 Windows 机器。

### 1. 准备系统环境

请先安装并确认以下组件：

1. `Miniconda` 或 `Anaconda`
2. `Google Chrome` 或 `Microsoft Edge`
3. Visual Studio C++ 编译环境

Windows 侧编译 `.pyd` 需要本机有 C/C++ 编译器。建议安装以下任意一种：

- Visual Studio Community，并勾选 `Desktop development with C++`
- Visual Studio Build Tools，并包含：
  - MSVC
  - Windows SDK
  - C++ build tools

建议你在安装后确认命令行可以直接识别：

```powershell
conda --version
cl
```

如果 `cl` 无法识别，建议改用以下终端运行构建：

- Developer PowerShell for VS 2022
- Developer Command Prompt for VS 2022

### 2. 准备项目代码

把整个项目目录复制到目标机器，或者用 Git 克隆：

```powershell
git clone <your-repo-url> spotify-python
cd spotify-python
```

### 3. 运行 Windows 构建脚本

在项目根目录执行：

```powershell
build_runtime_win.bat
```

这一步会自动完成下面这些工作：

1. 在项目根目录下创建 `python-runtime`
2. 安装 Python 3.11 和 `pip`
3. 安装运行依赖
4. 安装 `spotifyscraper`
5. 安装 `ShazamIO`
6. 临时安装 `Cython`
7. 将 `spotify_track_lookup.py` 编译为 `.pyd`
8. 将 `spotify_lookup_worker.py` 编译为 `.pyd`
9. 复制 `spotify_lookup_worker.py` 到 `python-runtime`
10. 删除构建期依赖、缓存和非必要目录

### 4. 构建完成后的目录结果

构建成功后，`python-runtime` 目录中至少会有这些关键文件：

- `python-runtime/python.exe`
- `python-runtime/spotify_track_lookup.cp311-win_amd64.pyd`
- `python-runtime/spotify_lookup_worker.cp311-win_amd64.pyd`
- `python-runtime/spotify_lookup_worker.py`

说明：

- 运行时不再依赖 `Cython`
- 运行时不会保留 `pip`、`setuptools`、`wheel`
- 运行时会删除 Python 缓存
- 运行时中会保留 `ShazamIO` 及其必要依赖
- 当前 Windows 实测裁剪后大小约为 80MB 左右，具体会随 Conda 和依赖版本变化

### 5. Windows 运行方式

构建完成后直接运行：

```powershell
.\python-runtime\python.exe .\python-runtime\spotify_lookup_worker.py --song "月球上的人" --artist "陳奕迅"
```

只传歌曲名：

```powershell
.\python-runtime\python.exe .\python-runtime\spotify_lookup_worker.py --song "Believer"
```

### 6. Windows 常见问题

#### `conda was not found in PATH`

说明当前终端里找不到 conda。请先确认：

- 已安装 Miniconda / Anaconda
- 已把 conda 加入 PATH
- 或者先执行 Conda 初始化，再开一个新终端

#### `cl` 编译失败或链接失败

说明当前机器缺少 Windows C++ 编译工具。请安装：

- Visual Studio Community 或 Build Tools
- 并确保包含 MSVC 和 Windows SDK

#### 浏览器启动失败

请确认本机已安装以下至少一个：

- Chrome
- Edge

#### Spotify / MusicBrainz 请求超时

请确认网络可以访问：

- `open.spotify.com`
- `musicbrainz.org`

并检查代理、证书或防火墙配置。

## macOS 安装与构建流程

下面的步骤适用于全新 macOS 机器。

### 1. 准备系统环境

请先安装并确认以下组件：

1. `Miniconda` 或 `Anaconda`
2. `Google Chrome` 或 `Microsoft Edge`
3. Xcode Command Line Tools

安装 Xcode 命令行工具：

```bash
xcode-select --install
```

检查是否安装成功：

```bash
conda --version
xcode-select -p
clang --version
```

### 2. 准备项目代码

复制项目目录，或者使用 Git 克隆：

```bash
git clone <your-repo-url> spotify-python
cd spotify-python
```

### 3. 给脚本执行权限

第一次使用前执行：

```bash
chmod +x build_runtime_mac.sh
```

### 4. 运行 macOS 构建脚本

在项目根目录执行：

```bash
./build_runtime_mac.sh
```

它会自动完成这些工作：

1. 在项目根目录创建 `python-runtime`
2. 安装 Python 3.11 和 `pip`
3. 安装运行依赖
4. 安装 `spotifyscraper`
5. 安装 `ShazamIO`
6. 临时安装 `Cython`
7. 把 `spotify_track_lookup.py` 编译成 macOS 对应扩展模块
8. 把 `spotify_lookup_worker.py` 编译成 macOS 对应扩展模块
9. 复制 `spotify_lookup_worker.py` 到 `python-runtime`
10. 删除构建依赖、缓存和非必要目录

### 5. macOS 构建完成后的结果

构建成功后，`python-runtime` 中关键文件一般类似：

- `python-runtime/bin/python`
- `python-runtime/spotify_track_lookup.<platform>.so`
- `python-runtime/spotify_lookup_worker.<platform>.so`
- `python-runtime/spotify_lookup_worker.py`

说明：

- macOS 下扩展模块后缀通常是 `.so`
- 具体文件名会带 Python 版本和架构信息
- 最终运行时同样不保留 `Cython` 和 Python 缓存
- 最终运行时会保留 `ShazamIO`

### 6. macOS 运行方式

构建完成后直接执行：

```bash
./python-runtime/bin/python ./python-runtime/spotify_lookup_worker.py --song "月球上的人" --artist "陳奕迅"
```

只传歌曲名：

```bash
./python-runtime/bin/python ./python-runtime/spotify_lookup_worker.py --song "Believer"
```

### 7. macOS 常见问题

#### `conda was not found in PATH`

说明当前 shell 没有加载 conda。请确认：

- 已安装 Miniconda / Anaconda
- 已执行 conda 初始化
- 已重新打开终端

#### `xcode-select was not found` 或 `Xcode Command Line Tools are not configured`

请执行：

```bash
xcode-select --install
```

如果已经装过但仍然报错，可尝试：

```bash
sudo xcode-select --switch /Library/Developer/CommandLineTools
```

#### 编译扩展模块失败

请优先检查：

- `clang --version` 是否可用
- Xcode 命令行工具是否正常
- 当前 macOS 架构是否与 Conda Python 架构一致

#### Intel Mac 安装 `ShazamIO` 失败

当前固定版本 `ShazamIO==0.8.1` 依赖 `shazamio-core==1.1.2`。

- Apple Silicon Mac 在 `Python 3.11` 下可以直接使用预编译 wheel
- Intel Mac 如果拿不到对应 wheel，则需要额外安装 `Rust` 和 `Cargo`

如果你是 Intel Mac，请先确认：

```bash
rustc --version
cargo --version
```

## 运行时最小化策略

当前构建脚本会在保证功能完整的前提下，尽量减小 `python-runtime` 体积。

目前会裁掉这些内容：

- `Cython`
- `pip`
- `setuptools`
- `wheel`
- `__pycache__`
- `.pyc`
- `.pyo`
- 调试符号文件
- 构建中间目录
- 部分 Conda 元数据和开发辅助目录

补充说明：

- `Cython` 只在构建阶段需要，运行阶段不需要
- 如果后续你还想进一步压缩，可以继续裁掉更多标准库内容，但需要一项项验证，不能盲删

## 推荐的最终调用方式

Windows：

```powershell
.\python-runtime\python.exe .\python-runtime\spotify_lookup_worker.py --song "月球上的人" --artist "陳奕迅"
```

macOS：

```bash
./python-runtime/bin/python ./python-runtime/spotify_lookup_worker.py --song "月球上的人" --artist "陳奕迅"
```

## 维护建议

如果你后续修改了：

- `spotify_track_lookup.py`
- `spotify_lookup_worker.py`
- `runtime-requirements.txt`
- `prune_runtime.py`

建议重新构建一次 `python-runtime`，不要直接把旧 runtime 继续复用。

推荐重建方式：

Windows：

```powershell
build_runtime_win.bat
```

macOS：

```bash
./build_runtime_mac.sh
```