music-lens 0.1.0 → 0.1.2

package/README.md

@@ -4,6 +4,10 @@
 
 不需要人耳，也不需要联网（模型已下到本地）。给纯文本的模型用：把声音变成它能读的数字和图。
 
+> **第一次用？看 [`docs/新手操作指南.md`](docs/新手操作指南.md)** —— 面向完全没写过代码的人，
+> 三步装好，七个坑都写在里面。
+> 要做视频/图文分享的话，[`docs/发布文案.md`](docs/发布文案.md) 里有标题、简介和口播稿。
+
 ```bash
 npm i -g music-lens        # 或者 git clone 后 npm i -g .
 music-lens setup           # 装 python 依赖 + 下模型（约 2 GB）
@@ -23,12 +27,16 @@ $node = "C:\Users\86173\Documents\deepseek-harness\default-workspace\snowluma\Sn
 & $node .\bin\music-lens.mjs analyze "song.mp3" --model medium
 ```
 
-`setup` 会自己装 python 依赖并从 hf-mirror 下模型：
+`setup` 会自己装 python 依赖并从 hf-mirror 下模型，**默认只下 small（461 MB）**：
 
 ```powershell
-& $node .\bin\music-lens.mjs setup --models small,medium
+& $node .\bin\music-lens.mjs setup              # small，约 500 MB 依赖 + 461 MB 模型
+& $node .\bin\music-lens.mjs setup --models medium   # 中文效果更好，再下 1.46 GB
 ```
 
+跨平台：Windows 用 `winget`，macOS 用 `brew`，Linux 用 `apt-get`；
+都不行时会打印手工安装命令，也可以用 `MUSIC_LENS_PYTHON` 直接指定解释器路径。
+
 模型和缓存默认放 `~/.music-lens`，可用 `MUSIC_LENS_HOME` 覆盖。
 
 > 本机注意：**node 不在 PATH 里，也没有 npm**，所以 `npx music-lens` 目前跑不了，
@@ -129,3 +137,17 @@ $base = "C:\Users\86173\Documents\deepseek-harness\default-workspace\music-lens"
 - [ ] 用 `librosa.pyin` 出逐帧基频，画"音高随时间的走向"
 - [ ] 情绪的 arousal 维度（能量+亮度已经能算个大概）
 - [ ] 换 `large-v3`（3 GB，CPU 上慢约 4 倍，中文应该更准）
+
+---
+
+## 致谢
+
+这个包的代码、文档、测试，以及下面那七条踩坑记录，全部由 **DSH（DeepSeek Harness）里的 AI 助手**
+在 2026-11-01 的一次会话中完成（模型 `deepseek-flash`）。
+
+它不能拥有账号、不能发布 npm 包、也不能处理 issue——所以仓库和包的所有权、维护责任在人类这边。
+这份致谢记录的是“谁写的”，不是转移责任。
+
+过程中被人类纠正过两次重要判断：先说“情绪和歌词做不出来”（错的，歌词能做），
+又说“节点不在 PATH 就装不了”（也是错的）。所以文档里那些边界条件，有一半是吵出来的。
+

package/bin/music-lens.mjs

@@ -57,13 +57,15 @@ function parseArgs(argv) {
 function candidates() {
   const list = []
   if (process.env.MUSIC_LENS_PYTHON) list.push(process.env.MUSIC_LENS_PYTHON)
-  const la = process.env.LOCALAPPDATA
-  if (la) {
-    for (const v of ['313', '312', '311']) {
-      list.push(path.join(la, 'Programs', 'Python', `Python${v}`, 'python.exe'))
+  if (process.platform === 'win32') {
+    const la = process.env.LOCALAPPDATA
+    if (la) {
+      for (const v of ['313', '312', '311']) {
+        list.push(path.join(la, 'Programs', 'Python', `Python${v}`, 'python.exe'))
+      }
     }
   }
-  list.push('python', 'python3')
+  list.push('python3.12', 'python3', 'python')
   return list
 }
 
@@ -135,8 +137,8 @@ function cmdDoctor() {
   const py = findPython()
   if (!py) {
     log('python          : MISSING')
-    log('  install:  winget install --id Python.Python.3.12 --scope user')
-    log('  or set MUSIC_LENS_PYTHON=C:\\path\\to\\python.exe')
+    log(`  install:  ${pythonInstallCommand().manual}`)
+    log('  or set MUSIC_LENS_PYTHON=/path/to/python')
   } else {
     const v = capture(py, ['-c', 'import sys;print(sys.version.split()[0])']).out.trim()
     log(`python          : ${py}  (${v})`)
@@ -151,16 +153,38 @@ function cmdDoctor() {
   return 0
 }
 
+function pythonInstallCommand() {
+  if (process.platform === 'win32') {
+    return {
+      cmd: 'winget',
+      args: ['install', '--id', 'Python.Python.3.12', '-e', '--scope', 'user',
+        '--accept-package-agreements', '--accept-source-agreements'],
+      manual: 'winget install --id Python.Python.3.12 -e --scope user',
+    }
+  }
+  if (process.platform === 'darwin') {
+    return { cmd: 'brew', args: ['install', 'python@3.12'], manual: 'brew install python@3.12' }
+  }
+  return {
+    cmd: 'sudo',
+    args: ['apt-get', 'install', '-y', 'python3', 'python3-pip', 'python3-venv'],
+    manual: 'sudo apt-get install -y python3 python3-pip python3-venv',
+  }
+}
+
 async function cmdSetup(args) {
   const py = findPython()
   let use = py
   if (!use) {
-    log('python not found -- trying winget (per-user install)')
-    const st = run('winget', ['install', '--id', 'Python.Python.3.12', '-e', '--scope', 'user',
-      '--accept-package-agreements', '--accept-source-agreements'])
-    if (st !== 0) die('python install failed; install it manually then re-run `music-lens setup`')
+    const inst = pythonInstallCommand()
+    log(`python not found -- trying ${inst.cmd}`)
+    let st = 1
+    try { st = run(inst.cmd, inst.args) } catch { st = 1 }
+    if (st !== 0) {
+      die(`could not install python automatically.\n  run manually:  ${inst.manual}\n  then re-run:   music-lens setup\n  (or point MUSIC_LENS_PYTHON at an existing python 3.9+)`)
+    }
     use = findPython()
-    if (!use) die('python installed but still not found; set MUSIC_LENS_PYTHON')
+    if (!use) die('python installed but still not on PATH; set MUSIC_LENS_PYTHON')
   }
   log(`python: ${use}`)
 
@@ -175,10 +199,11 @@ async function cmdSetup(args) {
       '--index-url', 'https://download.pytorch.org/whl/cpu'])
   }
 
-  const wanted = (args.models || 'small,medium').split(',').map(s => s.trim()).filter(Boolean)
+  const wanted = (args.models || 'small').split(',').map(s => s.trim()).filter(Boolean)
   for (const m of wanted) await ensureModel(m)
 
   log('\nready. try:  music-lens analyze "<song.mp3>" --model medium')
+  log('(medium is ~1.5 GB and a lot better on Chinese; download it with: music-lens setup --models medium)')
   return 0
 }
 
@@ -212,7 +237,7 @@ function usage() {
   log(`music-lens ${JSON.parse(fs.readFileSync(path.join(PKG, 'package.json'), 'utf8')).version}
 
   music-lens doctor                        check environment
-  music-lens setup [--models small,medium] install python deps + models
+  music-lens setup [--models small]         install python deps + models
   music-lens analyze <audio>               transcribe + analyse
               [--model medium]             small | medium | large-v3 | path
               [--lang auto]                language code or auto

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "music-lens",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Let a text-only model read a song: lyrics + timestamps, loudness, brightness, key, tempo, sections. Local, no API keys.",
   "type": "module",
   "bin": {