mytunes-pro 1.5.2

A lightweight, keyboard-centric terminal player for streaming YouTube music.

🎵 MyTunes Pro (Korean)

현대적인 CLI 유튜브 뮤직 플레이어 (v1.5.2)
터미널 환경에서 YouTube 음악을 검색하여 듣는 가볍고 빠른 키보드 중심의 플레이어입니다.
한국어 입력 환경에서도 **숫자 키(1~5)**를 통해 지연 없는 쾌적한 조작이 가능합니다.

💡 개발 배경
이 프로그램은 하루 종일 터미널을 보는 개발자들이 작업 흐름을 끊지 않고 편하게 음악을 듣기 위해 만들어졌습니다.
특히 **모니터가 없는(Headless) 미니 PC (Debian Server)**를 거실이나 책상의 '뮤직 스테이션'으로 활용하고자 했던 개인적인 필요에서 시작되었습니다.
복잡한 설정 없이, 터미널 하나만 있으면 어디서든 당신만의 오디오 플레이어가 됩니다.

📸 Screenshots

---

✨ 주요 기능

• 강력한 검색: yt-dlp 엔진을 사용하여 광고 없는 고음질 오디오 스트리밍.
• 쾌적한 조작: curses 기반 TUI로 빠르고 직관적인 인터페이스.
• 연속 재생: 한 곡이 끝나면 리스트의 다음 곡을 자동으로 재생합니다.
• 이어듣기: 중단된 위치부터 이어서 재생할지 선택할 수 있습니다.
• 한글 최적화: 한글 자소 조합 대기 시간 없이 즉시 반응하는 숫자 단축키 지원.
• 스마트 기능: 즐겨찾기, 재생 기록(최대 100곡), 자동 음악 필터링 검색.
• 비주얼: 현대적인 심볼 아이콘(⌕, ★, ◷)과 깔끔한 디자인.

---

💻 구동 환경 안내

MyTunes Pro는 터미널(CLI) 기반 애플리케이션입니다. 각 운영체제에서 고음질 오디오를 재생하기 위해 **mpv**라는 엔진을 사용합니다.

• macOS: 터미널(iTerm2, Warp 추천)에서 즉시 실행 가능.
• Linux: 우분투, 데비안 등 모든 리눅스 배포판 지원.
• Windows: WSL(Windows Subsystem for Linux) 환경이 필요합니다. (아래 가이드를 참고하세요.)

---

🚀 빠른 설치 (Quick Install)

최신 macOS/Linux 시스템(PEP 668)에서는 pipx 사용을 강력히 권장합니다.

1. 추천 방식 (pipx)

자동으로 격리된 환경을 만들고 명령어를 등록해줍니다.

brew install pipx    # macOS (설치 안 된 경우)
pipx install mytunes-pro
pipx ensurepath      # 터미널 명령어 경로 등록 (최초 1회 필수)

2. 일반 pip 방식

만약 externally-managed-environment 에러가 발생한다면 아래 플래그를 추가하세요:

pip install mytunes-pro --break-system-packages

설치 후 터미널 어디서든 **mp**를 입력하면 실행됩니다!

🔄 최신 버전 업데이트 (Update)

이미 설치되어 있다면 아래 명령어로 간단히 최신 기능을 반영하세요:

pipx upgrade mytunes-pro

---

🛠 환경별 요구사항 (Prerequisites)

pip install 이후 실행이 안 된다면, 각 운영체제에 맞는 오디오 엔진(mpv)을 설치해 주세요.

macOS

brew install mpv

Linux (Ubuntu/Debian)

sudo apt update && sudo apt install mpv

Windows (초보자용 WSL 가이드)

Windows 환경이 익숙한 일반인도 따라할 수 있는 완전 정복 가이드입니다.

❓ WSL이란?
윈도우 안에서 리눅스(강력한 개발 도구들)를 마치 일반 앱처럼 쓸 수 있게 해주는 마이크로소프트의 공식 기능입니다. MyTunes는 이 환경에서 리눅스의 강력한 오디오 엔진을 활용해 작동합니다.

1. WSL 설치하기:

   • 시작 버튼 우클릭 -> 터미널(관리자) 혹은 PowerShell(관리자) 실행.
   • 아래 명령어를 복사해서 붙여넣고 엔터!

     wsl --install -d Debian
     

   • 설치가 끝나면 컴퓨터를 다시 시작하세요.

2. 기본 설정:

   • 재부팅 후 데비안(Debian) 창이 자동으로 뜨면, 사용할 아이디(영문)와 비밀번호를 정하세요.

3. 필수 도구 설치:

   • 데비안 창에서 아래 명령어를 한 번에 복사해서 붙여넣으세요:

     sudo apt update && sudo apt install mpv python3-pip pipx -y
     

4. MyTunes 설치:

   • 이제 위 빠른 설치 섹션의 pipx install 과정을 그대로 따라하면 끝!

---

🧑‍💻 개발자용 수동 설치 (Manual Installation)

직접 소스를 수정하거나 개발 버전을 사용하려면 아래 과정을 따르세요.

1. 저장소 클론:

   git clone https://github.com/postgresql-co-kr/mytunes.git
   cd mytunes
   

2. 가상환경 설정:

   python3 -m venv venv
   source venv/bin/activate  # macOS/Linux
   pip install -r requirements.txt
   

3. 실행:

   python3 mytune.py
   

4. 업데이트:

   git pull
   

---

⌨️ 조작 방법 (Controls)

MyTunes Pro는 키보드만으로 모든 기능을 제어합니다.
한글 입력 상태에서도 끊김 없는 조작을 위해 숫자 단축키 사용을 권장합니다.

⚡️ 즉시 반응 단축키 (숫자키)

한영 전환 없이 언제든 누르면 즉시 실행됩니다.

키	기능	설명
1	검색 (Search)	음악 검색창 열기 (단축키 S와 동일)
2	즐겨찾기 (Fav)	저장된 즐겨찾기 목록 보기 (단축키 F와 동일)
3	기록 (History)	최근 재생한 100곡 보기 (단축키 R와 동일)
4	메인 (Main)	메인 화면으로 돌아가기 (단축키 M와 동일)
5	추가/삭제	선택한 곡 즐겨찾기 토글 (단축키 A와 동일)
+	볼륨 UP	볼륨 +5% (단축키 =와 동일)
-	볼륨 DOWN	볼륨 -5% (단축키 _와 동일)
6	뒤로가기	이전 화면으로 이동 (단축키 Q, H와 동일)
ESC	배경재생	음악 끄지 않고 나가기 (백그라운드 재생)

🧭 기본 탐색

키	동작
↑ / ↓ / k / j	리스트 위/아래 이동 (Vim 키 지원)
Enter / l	선택 / 재생 (한글 ㅣ도 지원)
Space	재생 / 일시정지 (Play/Pause)
- / +	볼륨 조절 (- / +)
, / .	10초 뒤로 / 앞으로 감기
< / >	30초 뒤로 / 앞으로 감기 (Shift)
Backspace / h / q	뒤로 가기 / 검색어 지우기
/	검색 (Vim Style)

---

📂 데이터 저장

• 즐겨찾기와 재생 기록은 홈 디렉토리의 ~/.pymusic_data.json 파일에 영구 저장됩니다.
• 프로그램 종료 후 다시 실행해도 데이터가 유지됩니다.

---

---

🎵 MyTunes Pro (English)

Modern CLI YouTube Music Player (v1.5.2)
A lightweight, keyboard-centric terminal player for streaming YouTube music.
Designed for speed and efficiency, with optimized controls for international keyboard imports.

💡 Preface
This project was created to give developers a seamless way to enjoy music without leaving their terminal environment.
It basically started from a personal need to turn a headless mini-PC running Debian Server into a dedicated living room music station.

---

💻 Environment Support

MyTunes Pro is a Terminal-native application. It uses the mpv engine for high-quality audio playback.

• macOS: Runs natively in Terminal (iTerm2, Warp recommended).
• Linux: Supports all distributions (Ubuntu, Debian, etc.).
• Windows: Requires WSL (Windows Subsystem for Linux). See the guide below.

---

🚀 Quick Start

On modern macOS/Linux systems (PEP 668), using pipx is highly recommended.

1. Recommended (pipx)

Automatically manages virtual environments and global paths.

brew install pipx    # macOS (if not installed)
pipx install mytunes-pro
pipx ensurepath      # Registers command paths (required once)

2. Standard pip

If you encounter an externally-managed-environment error, use this flag:

pip install mytunes-pro --break-system-packages

Run simply by typing mp in your terminal!

🔄 How to Update

If already installed, update to the latest version with one command:

pipx upgrade mytunes-pro

---

🛠 Prerequisites

If the command fails, please ensure the mpv audio engine is installed.

macOS

brew install mpv

Linux (Ubuntu/Debian)

sudo apt update && sudo apt install mpv

Windows (Beginner's WSL Guide)

A step-by-step guide for Windows users to get started with CLI tools.

❓ What is WSL?
It stands for "Windows Subsystem for Linux". It's an official Microsoft feature that lets you run Linux powerful tools directly inside Windows like a regular app.

1. Install WSL:

   • Right-click Start -> Select Terminal (Admin) or PowerShell (Admin).
   • Paste this command and hit Enter:

     wsl --install -d Debian
     

   • Restart your computer after installation.

2. Basic Setup:

   • After restart, the Debian window will pop up. Choose your username and password.

3. Install Core Tools:

   • Inside the Debian window, run:

     sudo apt update && sudo apt install mpv python3-pip pipx -y
     

4. Install MyTunes:

   • Follow the Quick Start section above inside the Debian window. Done!

---

🧑‍💻 Manual Installation (For Developers)

1. Clone Repository:

   git clone https://github.com/postgresql-co-kr/mytunes.git
   cd mytunes
   

2. Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate  # macOS/Linux
   pip install -r requirements.txt
   

3. Run:

   python3 mytune.py
   

4. How to Update:

   git pull
   

---

⌨️ English Controls

⚡️ Instant Shortcuts (Number Keys)

Works instantly even with non-English keyboard layouts.

Key	Function	Description
1	Search	Open search bar (Same as S)
2	Favs	View favorites list (Same as F)
3	Hist	View history (Same as R)
4	Main	Go to Main Menu (Same as M)
5	Add/Del	Toggle Favorite (Same as A)
+	Vol Up	Volume +5% (Same as =)
-	Vol Down	Volume -5% (Same as _)
6	Back	Go back (Same as Q, H)
ESC	Bg Play	Exit app but keep music playing

🧭 Navigation

Key	Action
↑ / ↓ / k / j	Move selection (Vim style supported)
Enter / l	Select / Play (Includes L)
Space	Play / Pause
- / +	Volume (- / +)
, / .	Seek -10s / +10s
< / >	Seek -30s / +30s (Shift)
Backspace / h / q	Go back
/	Search (Vim Style)