By HerbertGao
Convert QQ Music .ogg/.oggh files to MP3 with embedded cover art and metadata on macOS, batch-process directories, inspect file metadata, and check environment dependencies—all via slash commands or natural language.
QQ 音乐 Mac 版 .ogg / .oggh 音频转 .mp3 脚本,自动保留专辑封面和元数据。既是 CLI 工具,也是 Claude Code / Codex CLI 的 Plugin & Skill——可以在终端直接调,也可以用自然语言驱动 AI Agent 完成转换。
QQ 音乐默认下载格式后缀已从
.oggh改为.ogg,本脚本两者都支持。 文件本质是 Vorbis 音频 + macOS Resource Fork 里的 ICNS 专辑封面(10 张图标),封面没有写在音频流或 metadata 里,必须用derez单独提取出来。
ffprobe 从 OGG 流和 format 里抽元数据(title / album / artist / date / genre / track 等)derez 把 Resource Fork 里的 ICNS 提出来,icnsutil 拆成多分辨率 PNG,先用 ffmpeg 验证哪张是合法 PNG(icnsutil 会把 JP2K 之类 ICNS 子类型也写成 .png,要剔除),再选最高分辨率ffmpeg 调用同时完成:音频转码 MP3、嵌入元数据、嵌入封面(id3v2.3)git clone https://github.com/HerbertGao/ogg2mp3
cd ogg2mp3
bash scripts/install.sh # 软链 ogg2mp3.sh → ~/.local/bin/ogg2mp3
ogg2mp3 doctor # 自检依赖
install.sh 幂等可重跑,拒绝 root 运行,会检测 ~/.local/bin 是不是已经在 PATH 里。
直接
./ogg2mp3.sh <command>也能用,但 AI Agent 调用、跨目录使用都依赖 PATH 安装。建议跑一次install.sh。
ogg2mp3 <command> [args] [flags]
ogg2mp3 # 交互菜单(无参运行)
convert <input> 转换单个 .ogg/.oggh 文件
batch <dir> 批量转换目录
inspect <input> 只读:dump 元数据 + 封面信息
doctor 依赖与环境自检
help | version
ogg2mp3 convert song.ogg # 输出 song.mp3
ogg2mp3 convert song.ogg -o /tmp/out.mp3 # 自定义输出
ogg2mp3 convert song.ogg --no-cover # 跳过封面
ogg2mp3 convert song.ogg --overwrite --yes # 非交互覆盖
ogg2mp3 convert song.ogg --json # JSON 结果
ogg2mp3 batch ~/Music/QQ音乐 # 仅顶层
ogg2mp3 batch ~/Music/QQ音乐 -r --skip-existing # 递归 + 跳过已转换
ogg2mp3 batch ~/Music/QQ音乐 -r --dry-run # 只列出会做什么
ogg2mp3 batch ~/Music/QQ音乐 -r --overwrite --json # NDJSON 输出供 Agent 消费
--skip-existing 与 --overwrite 互斥;两者都不加时已存在的输出会被记为 FAIL(保护性默认)。
ogg2mp3 inspect song.ogg # 人类可读
ogg2mp3 inspect song.ogg --json # JSON:file / codec / duration / bitrate / metadata / cover
ogg2mp3 doctor # 检查 ffmpeg/ffprobe/derez/icnsutil/jq/xxd 等是否就绪
ogg2mp3 doctor --json # 机器可读,含 binary_version 顶层字段
这个仓库本身就是 Claude Code + Codex CLI 双 host 的 Plugin Marketplace。装好以后,你可以在 host 里用自然语言驱动转换,不用记 flag。
在 Claude Code 终端里:
/plugin marketplace add HerbertGao/ogg2mp3
/plugin install ogg2mp3@ogg2mp3
owner/repo简写、https://github.com/HerbertGao/ogg2mp3、或本地 clone 路径都支持。Claude Code 从仓根.claude-plugin/marketplace.json读 marketplace 入口。
然后就有了:
/ogg2mp3:doctor、/ogg2mp3:convert <file>、/ogg2mp3:batch <dir>、/ogg2mp3:inspect <file>codex plugin marketplace add HerbertGao/ogg2mp3 --sparse .agents/plugins
Codex 的 marketplace 入口在 .agents/plugins/marketplace.json,所以加 --sparse .agents/plugins 走稀疏检出。装好后 Codex 也能用自然语言驱动同款 4 个能力。
packaging/skill/ogg2mp3/SKILL.md 是唯一被维护的 Skill 描述。scripts/sync-skill.sh 把它字节级同步到两个 host 的副本,避免漂移--yes 的写操作 —— 在非交互上下文会立即 exit 1)--json 输出都有写死的 schema,doctor 顶层带 binary_version 让 Agent 校验最低版本(当前 min_binary_version: 2026.5.0)| 流 | 内容 |
|---|---|
stdout | 数据:convert 输出最终路径一行;batch 每行 OK\t<path> / FAIL\t<path>\t<reason> / SKIP\t<path>;--json 模式输出结构化 JSON |
stderr | 全部日志(进度、警告、错误) |
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 业务失败(转换失败 / batch 有任何失败项) |
| 2 | 参数错误 |
| 3 | 依赖缺失 / 以 root 身份运行(被 require_unprivileged 拒绝) |
| 130 | 用户中断(Ctrl-C) |
derez):xcode-select --installpipx install icnsutil(如果没有 pipx:brew install pipx。新 macOS 上 PEP 668 拦截裸 pip3 install,所以走 pipx)brew install ffmpegbrew install jq不知道缺啥就跑 ogg2mp3 doctor,缺什么会原样给出对应的 install_hint。
ogg2mp3.sh # 主 CLI
scripts/
├── install.sh # 软链到 ~/.local/bin
└── sync-skill.sh # SOT → 两个 host 副本
packaging/
├── skill/ogg2mp3/SKILL.md # SOT(唯一真相源)
├── claude-code/ # Claude Code plugin
│ ├── .claude-plugin/plugin.json
│ ├── commands/{doctor,convert,batch,inspect}.md
│ └── skills/ogg2mp3/SKILL.md # 副本,由 sync-skill.sh 维护
└── codex/ # Codex CLI plugin(schema 与 Claude 不同)
├── .codex-plugin/plugin.json
└── skills/ogg2mp3/SKILL.md # 副本
.claude-plugin/marketplace.json # Claude Code marketplace 入口
.agents/plugins/marketplace.json # Codex marketplace 入口
CalVer,3 段格式(年.月.补丁号)—— 三段是 Codex plugin manifest 强制要求的 strict semver 兼容。当前 2026.5.0。
MIT
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
npx claudepluginhub herbertgao/ogg2mp3 --plugin ogg2mp3Manage multiple WeChat instances on macOS via natural language. Provides /double-wechat:* slash commands and a Skill description; all writes run unprivileged.
Operate the user's own X (Twitter) Likes via natural language — list, download media, check auth health. Backed by a local x_likes_downloader MCP server.
Orchestrated OpenSpec apply — the main agent groups pending tasks by scope, dispatches a subagent per group (parallel then serial by dependency), and only manages OpenSpec state and reviews; it never writes implementation code itself. Ships as /opsx:apply-subagent plus its SOT skill.
Adversarial review loop that iterates your proposal and diff to a clean pass — parallel Codex + Code Reviewer + Reality Checker review, merge/triage, minimal-change fixes, re-review until APPROVE/CLEAR or a configurable round cap.
Comprehensive skill pack with 66 specialized skills for full-stack developers: 12 language experts (Python, TypeScript, Go, Rust, C++, Swift, Kotlin, C#, PHP, Java, SQL, JavaScript), 10 backend frameworks, 6 frontend/mobile, plus infrastructure, DevOps, security, and testing. Features progressive disclosure architecture for 50% faster loading.
Intelligent draw.io diagramming plugin with AI-powered diagram generation, multi-platform embedding (GitHub, Confluence, Azure DevOps, Notion, Teams, Harness), conditional formatting, live data binding, and MCP server integration for programmatic diagram creation and management.
Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).
Complete creative writing suite with 10 specialized agents covering the full writing process: research gathering, character development, story architecture, world-building, dialogue coaching, editing/review, outlining, content strategy, believability auditing, and prose style/voice analysis. Includes genre-specific guides, templates, and quality checklists.
TypeScript/JavaScript full-stack development with NestJS, React, and React Native
Give your AI a memory — mine projects and conversations into a searchable palace. 33 MCP tools, auto-save hooks, and guided setup.