first commit

README.md

@@ -0,0 +1,90 @@
+# TUI Music Player
+
+외부 앱 없이 동작하는 크로스플랫폼 TUI 음악 플레이어입니다.
+
+터미널 UI는 ANSI escape sequence와 OS별 키 입력 처리로 구현했고, 재생 엔진은 단일 헤더 라이브러리인 `miniaudio`를 `vendor/miniaudio.h`에 포함했습니다.
+
+## Requirements
+
+- Windows, macOS, Linux
+- C11 compiler
+- CMake 3.16+ 또는 `make`
+
+## Build
+
+### Nix devshell
+
+```sh
+nix develop
+tui-build
+tui-run
+```
+
+한 줄로 실행할 수도 있습니다.
+
+```sh
+nix develop -c tui-run
+```
+
+devshell에는 `cmake`, `ninja`, `make`, `pkg-config`, `clang-tools`와 플랫폼별 오디오 빌드/런타임 패키지가 포함됩니다.
+
+### CMake
+
+```sh
+cmake -S . -B build
+cmake --build build
+```
+
+Windows에서는 Visual Studio, Ninja, MinGW 같은 CMake generator를 사용할 수 있습니다.
+
+### Make
+
+```sh
+make
+./tui-music-player
+```
+
+Windows + MinGW에서는 결과물이 `tui-music-player.exe`로 생성됩니다.
+
+## Add Music
+
+가장 쉬운 방법은 프로젝트의 `music/` 폴더에 음악 파일을 넣는 것입니다.
+
+```text
+TUIMusicPlayer/
+  music/
+    first-song.mp3
+    second-song.wav
+```
+
+앱을 실행하면 `music/` 안의 오디오 파일을 자동으로 플레이리스트에 넣습니다. 실행 중 파일을 추가했다면 `r` 키로 다시 스캔할 수 있습니다.
+
+파일 경로를 직접 넘겨서 시작할 수도 있습니다.
+
+```sh
+./tui-music-player ~/Music/song.mp3 ~/Music/another.wav
+```
+
+실행 중에는 `a` 키로 파일 경로를 직접 추가할 수 있습니다.
+
+`miniaudio`는 WAV/FLAC/MP3 등 일반적인 로컬 오디오 파일을 디코딩할 수 있습니다.
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| `j` / `Down` | Move selection down |
+| `k` / `Up` | Move selection up |
+| `Enter` | Play selected track |
+| `p` / `P` / Space | Pause or resume |
+| `s` / `S` | Shuffle playlist |
+| `a` | Add a track path after the selected row |
+| `r` | Rescan `music/` and add new files |
+| `d` / `x` | Delete selected track |
+| `n` | Next track |
+| `b` | Previous track |
+| `g` | Jump to top |
+| `G` | Jump to bottom |
+| `q` | Quit |
+
+Vim 스타일 이동을 기본으로 두고, 요청하신 `P`와 `S`도 대문자 그대로 동작합니다.