melody-tui 0.4.3__tar.gz

melody_tui-0.4.3/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - release-v*
+      - bugfix-*
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Python 3.13 / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "0.13.0"
+          enable-cache: true
+      - name: Install mpv on Linux
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y mpv
+      - name: Install mpv on macOS
+        if: runner.os == 'macOS'
+        run: brew install mpv
+      - name: Install locked dependencies
+        run: uv sync --locked --python 3.13
+      - name: Check formatting
+        run: uv run --no-sync black --check src tests
+      - name: Lint
+        run: uv run --no-sync ruff check src tests
+      - name: Test
+        run: uv run --no-sync pytest -q
+      - name: Build distributions
+        run: uv build
+      - name: Verify installed wheel outside the repository
+        run: bash scripts/check_install.sh
+      - name: Upload distributions
+        if: runner.os == 'Linux'
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error

melody_tui-0.4.3/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing GitHub Release tag to publish
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish release distributions
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/melody-tui/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          version: "0.13.0"
+      - name: Download GitHub Release distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ inputs.tag || github.event.release.tag_name }}
+        run: |
+          gh release download "$RELEASE_TAG" --dir dist \
+            --pattern 'melody_tui-*.whl' --pattern 'melody_tui-*.tar.gz'
+      - name: Publish to PyPI with Trusted Publishing
+        run: uv publish --trusted-publishing always dist/*

melody_tui-0.4.3/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+.codegraph/

melody_tui-0.4.3/AGENTS.md

@@ -0,0 +1,62 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Music TUI uses distribution name `melody-tui`, command `music-tui`, and import package `music_tui`. QQ Music and NetEase Cloud Music are supported.
+
+Source lives in `src/music_tui/`: `app.py` owns the Textual interface and playback queue, `screens.py` contains feature dialogs, `playback_screen.py` shows the independent player page, `history_screen.py` displays recent songs and sources, `session.py` saves preferences and account-scoped sessions and history, `models.py` defines shared values, `sources/qqmusic.py` and `sources/netease.py` own platform access and credentials, and `player.py` controls mpv through a Unix socket. Tests live in `tests/`, grouped by behavior. `docs/tui-preview.png` shows the interface. `pyproject.toml` declares dependencies; `uv.lock` pins versions. Consult `docs/python-project-structure.md` when changing module boundaries.
+
+## Build, Test, and Development Commands
+
+Use Python 3.13+, uv, and mpv. On macOS: `brew install uv mpv`.
+
+- `uv sync --locked`: install locked dependencies.
+- `uv run music-tui`: start the last used platform, or QQ Music on first use.
+- `uv run music-tui --source netease`: start NetEase with the local API service described in `README.md`.
+- `uv build`: build distribution archives with Hatchling.
+- `bash scripts/check_install.sh`: verify the built wheel in a new environment outside the repository.
+- `uv run black src tests`: format Python after every code change.
+- `uv run black --check src tests`: verify formatting before delivery.
+- `uv run ruff check src tests`: check configured lint rules.
+- `uv run pytest -q`: run all tests.
+- `uv run pytest -q tests/test_app.py`: run interface tests.
+
+## Coding Style & Naming Conventions
+
+Use four-space indentation and a 100-character line limit. Use `snake_case` for functions and variables, `PascalCase` for classes, and `UPPER_CASE` for constants. Follow adjacent annotations and async patterns. Keep UI, music access, and mpv lifecycle responsibilities separate.
+
+Black is the formatter; Ruff is the linter. After each Python change, run Black. Before delivery, check formatting and lint. Every Python file needs a module docstring. Every function and method, including test helpers, needs a concise docstring explaining purpose and relevant behavior.
+
+## Testing Guidelines
+
+Use pytest and pytest-asyncio with automatic asyncio mode. Name files `test_*.py` and functions `test_<behavior>`. Exercise UI through Textual's `app.run_test()` and pilot controls. Use fake music responses for offline tests. Player integration tests require mpv and generate local silent WAV files. Cover changed behavior and important failures; no numeric coverage threshold is configured.
+
+## Commit & Pull Request Guidelines
+
+Keep `main` as the stable integration branch. Use `release-v<major>.<minor>.<patch>` for new features and release preparation for that version, for example `release-v0.2.0`. Create a separate `bugfix-<short-kebab-case-description>` branch from `main` for each defect, for example `bugfix-playback-retry`. Integrate completed fixes into `main` and the active release branch when applicable. Check the current branch before editing code and keep each branch's changes focused on its purpose.
+
+Use concise, imperative commit subjects. PRs should describe resulting behavior, link relevant issues, and report checks. Include 80×24 terminal screenshots for layout changes.
+
+Every completed update includes publishing a new version and updating this machine's global installation with `uv tool install --force <released-wheel>`. Use the version requested by the user when specified. Verify `music-tui -v` and `music-tui --version` from outside the checkout match the released version before reporting completion.
+
+## Credentials & Configuration
+
+QQ credentials remain at `~/.local/share/qqmusic-tui/credential.json`, respecting `XDG_DATA_HOME`. Preserve `0600` permissions. NetEase cookies live at `~/.local/share/music-tui/netease/netease-credential.json` with `0600` permissions. The NetEase API service must run with `ENABLE_GENERAL_UNBLOCK=false`. Keep account data out of commits and fixtures.
+
+## Agent Collaboration
+
+Delegate independent parallel tasks to sub-agents with explicit inputs, outputs, file ownership, and completion criteria. The main agent integrates and verifies results. Keep tasks with shared state or sequential decisions together.
+
+## Agent skills
+
+### Issue tracker
+
+规格与任务使用 GitHub Issues（FlyTOmeLight/music-tui）。发布、读取和任务依赖约定见 `docs/agents/issue-tracker.md`。
+
+### Triage labels
+
+使用默认五种状态标签；角色与标签映射见 `docs/agents/triage-labels.md`。
+
+### Domain docs
+
+项目采用单一领域上下文。探索和编写规格前读取 `CONTEXT.md` 与相关 ADR；详细约定见 `docs/agents/domain.md`。

melody_tui-0.4.3/CHANGELOG.md

@@ -0,0 +1,129 @@
+# 更新记录
+
+## v0.4.3
+
+- PyPI 发布包改名为 `melody-tui`，保留 `music-tui` 命令、`music_tui` 导入包及本机账号与配置目录。
+- 更新安装、版本读取及打包验证；GitHub Release 产物通过 Trusted Publishing 自动发布到 PyPI。
+
+## v0.4.2
+
+- 重写 README，补充 PyPI 安装与升级，按首次登录、网易云配置、日常操作、快捷键和常见问题组织说明。
+- 发布包包含 README 项目介绍和仓库、反馈、更新记录链接；修正网易云配置指南中过时的官方平台菜单说明。
+
+## v0.4.1
+
+- 喜欢状态刷新开始时立即显示未知标记 `?`；查询失败后不再沿用旧缓存。再次点击或按 `s` 时先查询真实状态，查询失败不会提交修改。
+- 写入失败仍保留已确认状态；刷新与正在提交的喜欢操作保持串行，不让迟到的写入重新填充已失效的缓存。
+
+## v0.4.0
+
+- QQ 与网易云 Enhanced 新增歌手详情页，支持头像、简介及全列表热门／最新排序；可点击每位歌手名进入，键盘按 `i` 选择合唱歌手。
+- 从歌手页选歌后按所选顺序跨页播放，歌手来源贯通最近播放、定位、手动待播与播放会话恢复；浏览或切换排序不改变当前队列。
+- 搜索结果显示可点击的喜欢状态，与 `s` 键同步；未登录或查询失败显示未知，修改失败保留确认值，账号与平台切换隔离状态。
+- 主界面底部新增上一首、暂停／继续、下一首按钮，保留快捷键及 80×24 终端布局。
+- 实测并修正 QQ 歌手歌曲分页的数量参数，记录两平台排序与分页接口依据。
+
+## v0.3.8
+
+- 播放队列集中管理手动待播优先级、返回原列表、稳定身份编辑、单曲循环和失败导航重试，界面不再直接修改队列与随机历史。
+- 队列返回只读视图与导航结果；播放会话由队列导出独立快照，保持现有文件格式，恢复时复制可变数据。
+- 明确区分重播当前歌曲和重试失败导航，保留切换音质时的歌曲、进度与暂停状态；已结束队列不被 F5 重播。
+- 队列规则改为直接通过队列 interface 测试，保留界面快捷键、音频、事件、导航并发和会话恢复的集成测试。
+
+## v0.3.7
+
+- 加载歌曲期间保留 mpv 的结束与解码错误事件，避免无声时仍显示播放，或歌曲结束后未切下一首。
+- F5 支持在首次选歌前恢复启动失败或已退出的播放器；重试按钮在播放器未就绪时可用。
+- 网易云 Enhanced 扫码使用独立 Cookie 会话，验证和保存凭据成功后才切换账号；失败或取消保留原账号。
+- 修改本机服务端口或运行参数后，启动命令会更新已注册的 launchd 服务；相同配置重复启动保持不变。
+- 将队列分页、随机导航和加载事件管理提取到 `playback_queue.py`；会话类型、编解码和恢复校验集中到 `playback_session.py`，沿用现有会话文件格式。
+- 新增加载期间事件、无歌曲时播放器恢复、账号切换失败、后台配置更新及跨页会话恢复的回归测试。
+
+## v0.3.6
+
+- 移除玻璃主题、`Ctrl+F9` 快捷键、终端磨砂设置说明和预览，仅保留日间、夜间和跟随系统三种主题设置。
+- 已保存的不支持主题设置改为跟随系统，避免升级后启动失败。
+
+## v0.3.5
+
+- 新增 `music-glass` 玻璃主题，沿用终端默认底色，以细边框和焦点高亮区分面板；浏览、播放、最近及弹窗统一配色。
+- `Ctrl+F9` 打开玻璃主题，再次按下恢复原来的昼夜设置；主题选择会保存。`F9` 手动切换昼夜，`Shift+F9` 恢复跟随系统。
+- README 增加 iTerm2 透明度与背景模糊设置说明，由终端提供实际磨砂效果。
+
+## v0.3.4
+
+- 网易云 Enhanced 播放失败时区分接口结果码、无播放地址、仅试听、音质不匹配和缺少歌曲音源，保留具体原因，不再推测会员权限。
+- 平台选择界面移除网易云官方入口和说明，仅显示 QQ 音乐与网易云 Enhanced；已有命令行接入保持可用。
+
+## v0.3.3
+
+- 获取音源中和失败后，浏览页底部保留歌曲名、歌手，失败后显示 F5 重试和 N 下一首。
+- 所有音质不可用时保留标准档的具体原因和 QQ 接口结果码，去除固定的会员权限推测。
+- 修复退出时系统主题检测仍更新已关闭页面的异步错误。
+
+## v0.3.2
+
+- 浏览页去除播放器、状态行和底栏之间重复的播放提示，状态行保留加载结果及错误。
+- 歌曲列表新增「[ 上一页」「下一页 ]」按钮，明确区分两个英文方括号按键；首尾页禁用不可用方向。
+- 矮窗口压缩搜索和筛选框，避免歌单页的翻页按钮挤入播放器区域。
+
+## v0.3.1
+
+- 新增 `music-tui -v` 和 `music-tui --version`，输出当前安装版本后退出。
+- wheel 安装验证检查两个版本参数；发布收尾增加本机全局安装更新与版本核验。
+
+## v0.3.0
+
+### 界面与歌单
+
+- 重整浏览、播放和最近页面的导航与昼夜配色。默认跟随系统外观，`F9` 手动切换，`Shift+F9` 恢复跟随；设置会保存。
+- 播放页通过概览、歌词和队列页签展示内容，歌词和队列不再使用弹窗。播放控制改为单行紧凑按钮，随终端宽度并排、上下排列或折为两列。
+- 播放概览展示真实歌曲封面，宽屏放大、窄屏缩小；普通终端使用真彩半块字符，封面加载失败不影响播放。
+- 歌曲列表支持当前页按歌曲、歌手、时长排序；歌单侧栏支持按名称或累计播放量排序。排序保留歌曲身份，播放队列仍按来源顺序运行。
+- QQ 音乐和网易云 Enhanced 支持新建歌单，以及新建后直接加入当前歌曲；播放页可把当前播放歌曲加入歌单。
+- 网易云官方后端支持把歌曲加入已有的自建歌单，暂不支持新建歌单。
+
+### 播放与修复
+
+- 当前歌曲的首选音质不可用时，按档位依次尝试至标准音质，显示实际档位和切换提示。保留首选音质，下一首仍从首选档开始；重载保留进度和暂停状态。
+- QQ 音源文件返回 404 或 410 时继续尝试下一档。连接超时、登录、服务端及播放器错误保持错误提示；所有档位不可用时不自动跳过歌曲。
+- 修复歌单排序与刷新并发时打开错误歌单、歌单写入过程中切换登录，以及平台切换后显示旧账号页面的问题。
+- 修复单行按钮焦点遮住文字、长歌曲信息被裁切，以及旧歌词或队列请求覆盖新歌曲的问题。
+- 修复系统外观读取失败的异步提示覆盖播放错误状态的问题。
+
+### 验证与接入范围
+
+- QQ 真实账号只读验证覆盖歌单、搜索、完整歌曲播放、音质自动降档、封面、歌词、暂停/继续和四种终端尺寸；可使用 `scripts/check_live_ui.py` 复跑。
+- 歌单创建及添加的成功与失败流程使用离线响应验证，未执行真实账号写入。
+- 个人单曲播放次数尚未提供；不接入需另行申请开通的腾讯 IoT 音乐服务。
+- Python、uv、mpv 和网易云本机服务的系统要求沿用 v0.2.0。
+
+## v0.2.0
+
+### 新增功能
+
+- 手动待播队列：浏览歌曲时可追加待播，F3 实时显示队列，支持删除、重排和清空手动待播项。手动歌曲听完后继续原歌单或搜索结果，分页、筛选和浏览保持独立。
+- 播放恢复：重试原来的失败歌曲，重新获取播放地址；mpv 退出后可在应用内重建播放器，保留最近记录的进度、暂停状态和音量。
+- 音频加载使用 mpv 命名参数，支持 Linux 发行版与 macOS 上不同版本的 mpv。
+- 播放会话与偏好：按平台保存音量、音质和播放模式，按平台与账号保存队列、手动待播、筛选结果、随机历史和进度。启动后由用户主动继续上次会话。
+- 同步歌词与译文：支持逐行显示、高亮当前歌词，无时间歌词可滚动阅读。
+- 喜欢与添加到歌单：QQ 音乐和网易云 Enhanced 支持喜欢、取消喜欢，以及把选中歌曲加入已有的可写歌单。
+- 最近播放：F8 查看当前账号最近播放的 100 首歌曲，同一歌曲重播后移至列表前方；可重播单曲、打开原来源，并切换查看最近来源与歌单。
+- 独立播放页：F7 集中查看当前歌曲、真实播放状态、进度、音量、音质、模式、来源和下一首，提供常用播放控制。
+- macOS 网易云后台服务：由 launchd 守护 Enhanced 服务，支持启动、状态查询和停止；关闭终端后继续运行，重复启动不创建多个服务。
+- 快捷键帮助、返回当前歌曲、刷新当前列表，以及歌曲区域的 PageUp / PageDown 翻页。
+- GitHub Actions：main、release-v*、bugfix-* 的提交和 Pull Request 自动执行 Linux/macOS 检查、全量测试、构建及全新环境 wheel 安装验证。
+
+### 接入与系统要求
+
+- 需要 Python 3.13+、uv 和 mpv；支持 macOS 和 Linux。音频播放使用本机 Unix socket。
+- 网易云 Enhanced 本机服务需要 Node.js 22+ 和 npx，固定使用 `@neteasecloudmusicapienhanced/api@4.41.1`。后台托管命令目前支持 macOS；其他系统可手动运行服务，已有远端服务无需本机 Node.js。
+- Enhanced 本机服务绑定 `127.0.0.1`，禁用全局解锁和代理功能。macOS 服务在当前登录会话运行，注销或重启后需要再次启动。
+- 网易云官方接入保留为可选后端，需要已获批的应用与设备配置；暂不支持歌词、喜欢状态查询和歌单写操作，会明确提示不支持，不自动切换后端。
+- 播放权限和音质由平台授权决定；不自动跳过权限错误、不降低音质。账号凭证与会话文件保持 `0600` 权限，会话不保存 Cookie 或播放地址。
+
+### 验证范围
+
+- 功能测试使用离线音乐响应；mpv 集成测试播放本地生成的静音音频。
+- 发布包验证从 wheel 安装到全新环境，并在仓库目录之外检查包版本、导入路径和 `music-tui --help`。
+- 新增喜欢、歌单写入和歌词功能未进行真实账号写入验收。

melody_tui-0.4.3/CONTEXT.md

@@ -0,0 +1,27 @@
+# Music TUI
+
+这里记录播放器的领域用语，用于说明歌曲顺序、来源与恢复的含义。
+
+## Language
+
+**播放队列**：一次选歌后形成的原列表及其手动待播歌曲，决定后续播放顺序。浏览其他列表不会改变它。
+
+**原列表**：建立播放队列时选中的歌单、搜索结果、筛选结果或歌手歌曲列表；手动待播播放完后继续这个列表。
+
+**手动待播**：用户主动插入的歌曲，优先于原列表的后续歌曲，并保留添加时的来源。
+
+**当前手动歌曲**：已经从手动待播中取出、正在播放或等待重试的歌曲；它不改变原列表的位置。
+
+**播放来源**：歌曲所属的歌单、搜索、筛选结果或带有热门／最新顺序的歌手歌曲列表，用于返回列表和定位歌曲。
+
+**播放会话**：某个平台账号保存的播放队列、播放位置和暂停状态，用户可以主动恢复。
+
+**重播当前歌曲**：再次加载当前选择的歌曲，不执行之前失败的导航。
+
+**重试**：再次执行未成功的操作，可能是导航到下一首，也可能是重新加载当前歌曲。
+
+**歌手详情页**：某位歌手的信息及其歌曲列表，用户可从歌曲的歌手名称进入。
+
+**歌手歌曲列表**：当前平台归属于指定歌手的歌曲集合，包含合唱歌曲；热门／最新顺序覆盖整个集合，而非仅当前页。
+
+**喜欢状态**：当前平台账号是否将某首歌曲加入「我喜欢」。它不等同于歌曲是否存在于其他歌单中。