music-lens 0.1.1 → 0.1.3

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）
@@ -19,10 +23,14 @@ music-lens analyze song.mp3
 ```powershell
 $node = "C:\Users\86173\Documents\deepseek-harness\default-workspace\snowluma\SnowLuma-v2.2.1\node.exe"
 & $node .\bin\music-lens.mjs doctor                       # 体检：python / 依赖 / 模型
+& $node .\bin\music-lens.mjs spectrogram "song.mp3"       # 10 秒出图，只要 ffmpeg
 & $node .\bin\music-lens.mjs separate "song.mp3"          # 分轨
 & $node .\bin\music-lens.mjs analyze "song.mp3" --model medium
 ```
 
+`spectrogram` 是**零依赖**的快速预览：频谱图 + 波形图，不装 Python、不下模型，
+只要机器上有 ffmpeg（`MUSIC_LENS_FFMPEG` 可指定路径）。
+
 `setup` 会自己装 python 依赖并从 hf-mirror 下模型，**默认只下 small（461 MB）**：
 
 ```powershell
@@ -133,3 +141,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

@@ -77,6 +77,22 @@ function findPython() {
   return null
 }
 
+// ffmpeg is optional: only the zero-dependency `spectrogram` command needs it.
+function findFfmpeg() {
+  const cands = []
+  if (process.env.MUSIC_LENS_FFMPEG) cands.push(process.env.MUSIC_LENS_FFMPEG)
+  cands.push('ffmpeg')
+  if (process.platform === 'win32') {
+    cands.push(path.join(os.homedir(), '.dsh', 'bili-whale', 'bin', 'ffmpeg.exe'))
+    cands.push('C:\\ffmpeg\\bin\\ffmpeg.exe')
+  }
+  for (const c of cands) {
+    const r = spawnSync(c, ['-version'], { encoding: 'utf8' })
+    if (r.status === 0) return c
+  }
+  return null
+}
+
 function run(cmd, args, opts = {}) {
   const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...process.env, ...(opts.env || {}) } })
   return r.status ?? 1
@@ -221,6 +237,44 @@ async function cmdAnalyze(args) {
   return run(py, argv)
 }
 
+/**
+ * Zero-dependency quick look: needs only ffmpeg, no python, no models.
+ * Produces a mel-ish spectrogram and a waveform picture.
+ */
+async function cmdSpectrogram(args) {
+  const audio = args._[0]
+  if (!audio) die('usage: music-lens spectrogram <audio> [--out DIR] [--size 1600x900]')
+  const src = path.resolve(audio)
+  if (!fs.existsSync(src)) die(`audio not found: ${src}`)
+
+  const ff = findFfmpeg()
+  if (!ff) {
+    die('ffmpeg not found.\n  install:  winget install Gyan.FFmpeg\n  or set:   MUSIC_LENS_FFMPEG=C:\\path\\to\\ffmpeg.exe')
+  }
+
+  const outDir = path.resolve(args.out || path.join(path.dirname(src), path.parse(src).name + '_look'))
+  fs.mkdirSync(outDir, { recursive: true })
+  const size = args.size || '1600x900'
+
+  log(`ffmpeg  : ${ff}`)
+  log(`output  : ${outDir}`)
+
+  const spec = path.join(outDir, 'spectrum.png')
+  const wave = path.join(outDir, 'waveform.png')
+
+  const st1 = run(ff, ['-y', '-hide_banner', '-loglevel', 'error', '-i', src,
+    '-lavfi', `showspectrumpic=s=${size}:legend=1:scale=log`, '-frames:v', '1', spec])
+  log(`  spectrum: ${st1 === 0 ? spec : 'FAILED'}`)
+
+  const st2 = run(ff, ['-y', '-hide_banner', '-loglevel', 'error', '-i', src,
+    '-lavfi', `showwavespic=s=${size}:split_channels=0:colors=#4a7ebb`, '-frames:v', '1', wave])
+  log(`  waveform: ${st2 === 0 ? wave : 'FAILED'}`)
+
+  if (st1 !== 0 && st2 !== 0) return 1
+  log('\nquick look done. for lyrics / key / tempo / numbers, run:  music-lens analyze "<same file>"')
+  return 0
+}
+
 async function cmdSeparate(args) {
   const audio = args._[0]
   if (!audio) die('usage: music-lens separate <audio> [--out DIR]')
@@ -242,6 +296,8 @@ function usage() {
               [--model medium]             small | medium | large-v3 | path
               [--lang auto]                language code or auto
               [--out DIR]                  output directory
+  music-lens spectrogram <audio>           quick look: spectrum + waveform (ffmpeg only,
+              [--size 1600x900]            no python, no models, ~10 seconds)
   music-lens separate <audio>              split vocals / instrumental (demucs)
 
 Outputs per song: 00_summary.md, 01_lyrics.txt, 02_transcript.json,
@@ -257,6 +313,7 @@ const map = {
   setup: cmdSetup,
   analyze: cmdAnalyze,
   separate: cmdSeparate,
+  spectrogram: cmdSpectrogram,
  }
 
 if (cmd === 'help' || cmd === '--help' || cmd === '-h') { usage(); process.exit(0) }

package/package.json

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