mytunes-pro 1.5.0

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

🎵 MyTunes Pro (Korean)

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

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

📸 Screenshots

---

✨ 주요 기능

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

이 프로그램은 오디오 재생을 위해 mpv가 시스템에 설치되어 있어야 합니다.

🚀 빠른 설치 (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)

1. WSL 설치: wsl --install -d Debian (PowerShell 관리자 권한)
2. 필수 도구: sudo apt update && sudo apt install mpv -y

---

🧑‍💻 개발자용 수동 설치 (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.0)
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 (with no monitor or GUI).
Just bring your terminal, and you have a full-featured audio player.

✨ Key Features

• Powerful Search: High-quality audio streaming via yt-dlp.
• Pagination: Explicit [ Load Next 20... ] button to load more results.
• Sequential Play: Automatically plays the next song in the list.
• Smart Resume: Option to resume playback from where you left off.
• Fast TUI: Responsive curses interface.
• Smart Shortcuts: Instant number keys (1-5) for quick navigation.
• Visuals: Clean aesthetic with system-style glyphs (⌕, ★, ◷).

This app requires mpv to be installed on your system.

🚀 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 (WSL)

1. Install WSL: wsl --install -d Debian (PowerShell Admin)
2. Install mpv: sudo apt update && sudo apt install mpv -y

---

🧑‍💻 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)