[!IMPORTANT] 이 문서는 involvex/youtube-music-cli의 비공식 포크로, 로컬 stdio MCP 서버를 추가한 버전입니다. 업스트림, YouTube 또는 Google과 제휴 관계가 아닙니다. 이 커스텀 포크는 소스에서 빌드되며 업스트림이 광고하는 npm 패키지가 아닙니다.

MCP 설치, 도구, 권한 및 클라이언트 구성에 대해서는 mcp/README.md를 참조하세요.

🎵 youtube-music-cli

YouTube Music을 위한 강력한 터미널 사용자 인터페이스(TUI) 음악 플레이어

기능 • 설치 • 사용법 • 플러그인 • 문서

기능

• 🎨 아름다운 TUI - React와 Ink로 구축된 풍부한 터미널 인터페이스

• 🔍 검색 - 노래, 앨범, 아티스트, 플레이리스트 찾기

• 📋 큐 관리 - 재생 큐 구축 및 관리

• ❤️ 즐겨찾기 - f 키로 트랙을 즐겨찾기에 등록하고 Shift+F로 확인

• 🔀 셔플 및 반복 - 여러 재생 모드

• 🎚️ 볼륨 제어 - 세밀한 볼륨 조절

• 💡 스마트 추천 - 관련 트랙 발견

• 🎨 테마 - Dark, Light, Midnight, Matrix 테마

• 🔌 플러그인 시스템 - 플러그인으로 기능 확장

• ⌨️ 키보드 중심 - 효율적인 vim 스타일 탐색

• 🖥️ 몰입 모드 - 오디오 비주얼라이저와 디스코 효과가 포함된 전체 화면 Windows TUI

• 💾 다운로드 - Shift+D로 트랙/플레이리스트/아티스트 저장

• 🏷️ 메타데이터 태깅 - 선택적 커버 아트와 함께 제목/아티스트/앨범 자동 태깅

• ⚡️ 셸 자동 완성 - ymc completions <bash|zsh|powershell|fish>는 소스하거나 저장할 수 있는 스크립트를 출력하여 CLI(ymc로도 사용 가능)가 하위 명령과 플래그를 탭으로 자동 완성하게 합니다

업스트림 프로젝트 지원

youtube-music-cli가 유용하다고 생각되면 업스트림 프로젝트의 개발을 지원해 주세요:

• ☕ Buy Me a Coffee

• 🪙 PayPal

• ⌨️ GitHub Sponsors

여러분의 지원은 이 프로젝트를 계속 살아있게 하고 개선하는 데 도움이 됩니다!

로드맵

전체 백로그는 SUGGESTIONS.md를 방문하고, 현재 구현 초점(크로스페이드 + 끊김 없는 재생)과 이퀄라이저/개선을 위해 계획된 다음 단계를 이해하려면 docs/roadmap.md를 사용하세요. 로드맵 문서는 리뷰어와 기여자가 일관성을 유지할 수 있도록 작업을 선택하는 방법도 설명합니다.

사전 요구 사항

필수:

• mpv - 오디오 재생용 미디어 플레이어

• yt-dlp - YouTube 오디오 추출

사전 요구 사항 설치

# With Scoop
scoop install mpv yt-dlp

# With Chocolatey
choco install mpv yt-dlp

brew install mpv yt-dlp

# Ubuntu/Debian
sudo apt install mpv
pip install yt-dlp

# Arch Linux
sudo pacman -S mpv yt-dlp

# Fedora
sudo dnf install mpv yt-dlp

설치

Node.js (권장)

Node.js 18+가 설치되어 있어야 합니다.

npm install -g @involvex/youtube-music-cli

Bun

bun install -g @involvex/youtube-music-cli

Homebrew

brew tap involvex/youtube-music-cli https://github.com/involvex/youtube-music-cli.git
brew install youtube-music-cli

GitHub 릴리스

https://github.com/involvex/youtube-music-cli/releases

설치 스크립트 (bash)

curl -fssl https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.sh | bash

설치 스크립트 (PowerShell)

iwr https://raw.githubusercontent.com/involvex/youtube-music-cli/main/scripts/install.ps1 | iex

소스에서

git clone https://github.com/involvex/youtube-music-cli.git
cd youtube-music-cli

# With bun (recommended for development)
bun install
bun run build
bun link

# With npm
npm install
npm run build
npm link

사용법

대화형 모드

TUI 실행:

youtube-music-cli

CLI 명령

# Play a specific track
youtube-music-cli play <video-id|youtube-url>

# Search for music
youtube-music-cli search "artist or song name"

# Play a playlist
youtube-music-cli playlist <playlist-id>

# Get suggestions based on current track
youtube-music-cli suggestions

# Playback control
youtube-music-cli pause
youtube-music-cli resume
youtube-music-cli skip
youtube-music-cli back

몰입 모드 (Windows)

실제 재생, 큐 제어 및 오디오 시각화가 포함된 전체 화면 비주얼 플레이어를 실행합니다. mpv와 yt-dlp가 필요합니다(일반 재생과 동일).

# Standard immersive mode
youtube-music-cli --win32

# Search and play immediately
youtube-music-cli --win32 --search "artist song"

# With disco mode enabled
DISCO_MODE=true youtube-music-cli --win32

# Standalone Windows binary (Bun compile)
bun run build:win32
dist/ymc-win32.exe

몰입 모드 단축키:

바닥글에는 한 줄에 셔플/반복/디스코 상태가 표시되고 다음 줄에 우선순위가 높은 단축키가 표시됩니다. 라이브러리 메뉴(L)에서 랜덤 즐겨찾기를 사용할 수 있습니다. 시스템 트레이 아이콘을 마우스 오른쪽 버튼으로 클릭하면 설정 또는 종료가 표시됩니다(assets/icon.ico 사용).

Bun 런타임에서 Windows 터미널이 포커스되지 않은 상태에서도 전역 미디어 키(Alt+미디어 키)가 작동합니다.

몰입형 재생 문제 해결

• 트랙 정보는 표시되지만 시간이 움직이지 않거나 오디오가 없음: Space를 눌러 재개하세요. 몰입 모드는 마지막 세션을 자동 시작합니다. mpv가 외부에서 일시정지된 경우(화면 공유, 포커스 손실), UI가 이제 PAUSED 상태와 동기화됩니다 — Space를 다시 누르세요.

• 화면 공유 (Discord, Teams, OBS): 원격 시청자는 "컴퓨터 소리 공유"/시스템 오디오 캡처를 활성화하지 않으면 PC 오디오를 듣지 못하는 경우가 많습니다. 이는 플레이어가 오디오를 사용자에게만 라우팅하는 것이 아니라 Windows 캡처 제한입니다.

• Win32 네이티브 기능에는 Bun 필요: 전역 단축키와 네이티브 콘솔 제목은 Bun을 통해 @bun-win32/*를 사용합니다. bun run dev:win32 또는 컴파일된 ymc-win32.exe 바이너리로 실행하세요.

셸 자동 완성

CLI와 함께 제공되는 경량 ymc 별칭을 통해 셸 완성 도우미를 생성하세요. ymc completions <bash|zsh|powershell|fish>를 실행하여 셸용 완성 스크립트를 출력한 다음 소스하거나 프로필에 저장하세요:

# Bash
source <(ymc completions bash)
ymc completions bash >> ~/.bash_completion

# Zsh
source <(ymc completions zsh)

# PowerShell
ymc completions powershell | Out-File -Encoding utf8 $PROFILE
Invoke-Expression (ymc completions powershell)

# Fish
ymc completions fish > ~/.config/fish/completions/ymc.fish

CLI를 별칭이나 스크립트 이름으로 전역 설치한 경우, 완성을 생성하기 전에 ymc가 동일한 바이너리를 가리키는지 확인하여 스크립트가 설치 경로와 일치하도록 하세요.

옵션

예시

# Launch with matrix theme at 80% volume
youtube-music-cli --theme=matrix --volume=80

# Search and play in headless mode
youtube-music-cli search "lofi beats" --headless

# Play with shuffle enabled
youtube-music-cli play dQw4w9WgXcQ --shuffle

키보드 단축키

전역

재생

탐색

다운로드

플러그인

youtube-music-cli를 플러그인으로 확장하세요!

플러그인 관리

TUI 모드: p를 눌러 플러그인 관리자를 엽니다.

CLI 모드:

# List installed plugins
youtube-music-cli plugins list

# Install from default repository
youtube-music-cli plugins install adblock

# Install from GitHub URL
youtube-music-cli plugins install https://github.com/user/my-plugin

# Enable/disable
youtube-music-cli plugins enable my-plugin
youtube-music-cli plugins disable my-plugin

# Update
youtube-music-cli plugins update my-plugin

# Remove
youtube-music-cli plugins remove my-plugin

사용 가능한 플러그인

플러그인 개발

플러그인 개발 가이드 및 플러그인 API 참조를 참조하세요.

# Start from a template
cp -r templates/plugin-basic my-plugin
cd my-plugin

# Edit plugin.json and index.ts
# Install for testing
youtube-music-cli plugins install /path/to/my-plugin

구성

구성은 ~/.youtube-music-cli/config.json에 저장됩니다:

{
	"theme": "dark",
	"volume": 70,
	"shuffle": false,
	"repeat": "off",
	"streamQuality": "high",
	"downloadsEnabled": false,
	"downloadDirectory": "D:/Music/youtube-music-cli",
	"downloadFormat": "mp3"
}

스트림 품질

다운로드 설정

• 설정(,)에서 다운로드 활성화/비활성화.

• 설정 → 다운로드 폴더에서 다운로드 디렉터리 설정.

• 설정 → 다운로드 형식에서 형식 선택 (mp3 또는 m4a).

• 다운로드는 다음과 같이 저장됩니다:

  • <downloadDirectory>/<artist>/<album>/<title>.mp3 (또는 .m4a)

• MP3/M4A 파일에는 메타데이터(title, artist, album)가 태깅되며 가능한 경우 커버 아트가 포함됩니다.

문제 해결

mpv를 찾을 수 없음

mpv가 설치되어 있고 PATH에 있는지 확인하세요:

mpv --version

시작 시 CLI는 이제 mpv와 yt-dlp를 확인합니다. 대화형 터미널에서는 (명시적 확인 후) 설치 명령을 자동으로 실행하도록 안내할 수 있습니다.

오디오 없음

1. 볼륨이 음소거되지 않았는지 확인 (=로 높이기)

2. yt-dlp가 작동하는지 확인: yt-dlp --version

3. 다른 트랙 시도

TUI 렌더링 문제

렌더링이 잘못된 것 같으면 터미널 창 크기를 조정하거나 앱을 다시 시작하세요.

플러그인이 로드되지 않음

1. plugin.json 구문이 유효한지 확인

2. 플러그인이 활성화되어 있는지 확인: youtube-music-cli plugins list

3. 로그에서 오류 확인

기여

기여는 언제나 환영합니다!

1. 저장소 포크

2. 기능 브랜치 생성: git checkout -b feature/my-feature

3. 변경 사항 적용

4. 테스트 실행: bun run test

5. 커밋: git commit -m 'feat: add my feature'

6. 푸시: git push origin feature/my-feature

7. Pull Request 열기

개발

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Lint and format
bun run lint:fix
bun run format

# Type check
bun run typecheck

기술 스택

• 런타임: Node.js 18+ / Bun

• UI 프레임워크: Ink (CLI용 React)

• 언어: TypeScript

• 오디오: mpv + yt-dlp

• API: YouTube Music Innertube API

라이선스

MIT © Involvex

문서 • 버그 신고 • 기능 요청

음악 애호가를 위해 ❤️로 제작됨