lyricli CLI는 Node만으로 실행되지만, 실제 오디오 분석은 Python backend runtime에 의존한다.

가장 먼저 이 명령으로 현재 머신 상태를 확인한다:

bun run lyricli -- doctor --json

• python3 실행 가능 여부
• ffprobe 가 PATH 에 있는지
• 핵심 Python 모듈 존재 여부
  • numpy
  • librosa
  • torch
  • qwen_asr
  • demucs
  • stable_whisper
  • faster_whisper
  • fugashi
  • pyopenjtalk
• 추천 엔진 경로와 다음 액션

doctor summary 에서 특히 바로 볼 값:

• status
• preferredEnginePath
• recommendedActions
• installPlan
• missingRequiredModules
• cpuOnly

실제 align / transcribe 실행이 backend import 오류로 실패하면, CLI error JSON 에도 아래가 함께 실린다:

• hintCommand
• missingPythonModule
• installHint

Required:

• numpy
• librosa
• torch
• qwen_asr
• ffprobe

Optional but recommended:

• demucs
• torchaudio compatibility

Notes:

• demucs 가 실패해도 lyricli 는 원본 오디오로 fallback 한다
• doctor 는 demucs 패키지 존재만 보지 않고 torchaudio import 가능 여부까지 같이 본다
• forced alignment 자체는 qwen_asr 가 없으면 실행할 수 없다

Required:

• numpy
• librosa
• torch
• qwen_asr
• ffprobe

Required:

• numpy
• librosa
• stable_whisper
• ffprobe

Required:

• numpy
• librosa
• faster_whisper
• ffprobe

1. doctor 로 현재 상태를 본다
2. ffprobe / torch / numpy / librosa 같은 공통 기반을 먼저 맞춘다
3. 기본 경로를 하나 선택한다
   • qwen3-align / qwen3-asr
   • 또는 stable-ts
   • 또는 faster-whisper
4. 그 다음에만 실제 benchmark full run 을 돌린다

Official open-source README 기준:

• qwen-asr 패키지를 권장
• fresh Python 3.12 환경 권장
• forced aligner 는 Qwen/Qwen3-ForcedAligner-0.6B

Reference:

• https://huggingface.co/Qwen/Qwen3-ASR-1.7B

Official archive README 기준 separation-only 설치:

• python3 -m pip install -U demucs

Reference:

• https://github.com/facebookresearch/demucs

Official README 기준:

• pip install faster-whisper

Reference:

• https://github.com/SYSTRAN/faster-whisper

Official README 기준:

• pip install -U stable-ts
• FFmpeg in PATH 필요

Reference:

• https://github.com/jianfch/stable-ts

• clean machine 에서 보장되는 것은 doctor 와 --dry-run control-plane 이다
• full inference 는 runtime 이 준비된 머신에서만 기대한다
• benchmark claims 는 doctor 결과와 함께 봐야 한다