README.md (5292B)
1 <p align="center">
2 <img src="assets/ommp_logo.png" alt="OMMP" width="560">
3 </p>
4
5 <p align="center">
6 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache 2.0"></a>
7 <a href="https://github.com/sqzer-x/ommp"><img src="https://img.shields.io/badge/platform-linux-lightgrey" alt="Platform"></a>
8 </p>
9
10 <p align="center">
11 A standalone terminal music player built with Rust.<br>
12 No MPD, no daemon — just run <code>ommp</code> and play.
13 </p>
14
15 <p align="center">
16 <img src="assets/screenshot.png" alt="OMMP Screenshot" width="800">
17 </p>
18
19 ---
20
21 ## Features
22
23 - **Music playback** — FLAC, MP3, M4A, OGG, WAV, Opus, AAC, WMA
24 - **Browse your library** — by artist, album, genre, format, directory, or playlist
25 - **Album art** — displayed natively in supported terminals
26 - **Search** — find any track instantly with filters like `artist:`, `album:`, `genre:`, `*.flac`
27 - **Playlists** — create, rename, delete, and bookmark your favorite tracks
28 - **Mouse friendly** — click, scroll, drag to resize panes
29 - **Remembers your settings** — volume, playlists, layout are saved between sessions
30 - **Live sync** — automatically picks up new or removed files in your music folder
31
32 ## Before You Start
33
34 ### Nerd Font (required)
35
36 OMMP uses [Nerd Font](https://www.nerdfonts.com/) icons throughout the interface. Without one installed, icons will appear as broken squares.
37
38 Recommended fonts: **JetBrainsMono Nerd Font**, **MesloLGS NF**, **FiraCode Nerd Font**
39
40 After installing, set it as your terminal's font.
41
42 ### Terminal
43
44 OMMP needs true colour (24-bit) support, which any current terminal has.
45
46 Album art is drawn as a real image in terminals that implement one of the
47 graphics protocols OMMP understands — the **Kitty graphics protocol**, **Sixel**,
48 or the **iTerm2 inline image protocol**. Which one is in use is detected at
49 startup; nothing to configure.
50
51 | Protocol | Terminals |
52 |----------|-----------|
53 | Kitty graphics | [Ghostty](https://ghostty.org/), [Kitty](https://sw.kovidgoyal.net/kitty/), [WezTerm](https://wezterm.org/), Konsole |
54 | Sixel | [foot](https://codeberg.org/dnkl/foot), WezTerm, xterm (built with Sixel), Contour |
55 | iTerm2 | WezTerm, Konsole |
56
57 Anything else falls back to block characters, which still shows the artwork —
58 just coarser. Note that GPU acceleration is unrelated: Alacritty is
59 GPU-accelerated but implements none of these, while xterm is not and supports
60 Sixel.
61
62 ### Audio
63
64 PulseAudio or ALSA is required for audio output on Linux.
65
66 ## Install
67
68 On Arch Linux:
69
70 ```bash
71 yay -S ommp
72 ```
73
74 Anywhere else, with [Rust](https://rustup.rs/) installed:
75
76 ```bash
77 cargo install ommp
78 ```
79
80 That's it. Now you can run `ommp` from anywhere:
81
82 ```bash
83 ommp
84 ```
85
86 <details>
87 <summary><code>ommp: command not found</code>?</summary>
88
89 `~/.cargo/bin` may not be in your PATH. Add this line to your `~/.bashrc` or `~/.zshrc`:
90
91 ```bash
92 export PATH="$HOME/.cargo/bin:$PATH"
93 ```
94
95 Restart your terminal to apply.
96
97 </details>
98
99 <details>
100 <summary>Build from source</summary>
101
102 ```bash
103 git clone https://github.com/sqzer-x/ommp.git
104 cd ommp
105 cargo build --release
106 ./target/release/ommp
107 ```
108
109 </details>
110
111 ## Usage
112
113 Place your music files in `~/Music` and run `ommp`. It will automatically scan all files and subdirectories.
114
115 Album art comes from the audio files themselves — whatever cover is embedded in the tags. Nothing to place alongside them.
116
117 ### Browsing
118
119 The screen is split into three panels:
120
121 - **Left** — Library browser (artists, albums, genres, etc. depending on the active tab)
122 - **Center** — Play queue
123 - **Right** — Album art / Clock (top) + Track info (bottom)
124
125 Switch browsing modes using the tabs at the top: Queue, Directories, Artists, Albums, Genre, Format, Playlists
126
127 ### Search
128
129 Press `Ctrl+S` to open the search modal. Results filter as you type.
130
131 You can also search by specific fields:
132
133 - `artist:radiohead` — search by artist
134 - `album:ok computer` — search by album
135 - `genre:rock` — search by genre
136 - `*.flac` — filter by format
137
138 ## Keybindings
139
140 Press `Ctrl+H` inside the app to view the full keybinding list at any time.
141
142 ### Playback
143
144 | Key | Action |
145 |-----|--------|
146 | `Space` | Play / Pause |
147 | `n` / `N` | Next / Previous track |
148 | `+` / `-` | Volume up / down |
149 | `Left` / `Right` | Seek backward / forward 5s |
150 | `s` | Toggle shuffle |
151 | `r` | Cycle repeat (off / all / one) |
152
153 ### Navigation
154
155 | Key | Action |
156 |-----|--------|
157 | `j` / `k` | Move down / up |
158 | `h` / `l` | Focus previous / next panel |
159 | `Tab` / `Shift+Tab` | Cycle panel focus |
160 | `1`–`7` | Switch tab |
161 | `Enter` | Play selected item |
162 | `g` / `G` | Jump to top / bottom |
163 | `d` | Remove from queue |
164 | `b` | Add to playlist |
165 | `p` | Toggle info panel (Clock / Album Art) |
166 | `c` | Clear queue |
167 | `q` | Quit |
168 | `Ctrl+C` | Quit |
169
170 ### Commands
171
172 | Key | Action |
173 |-----|--------|
174 | `Ctrl+S` | Search |
175 | `Ctrl+H` | Help |
176 | `Ctrl+A` | About OMMP |
177 | `Ctrl+L` | Rescan library |
178
179 ### Mouse
180
181 | Action | Effect |
182 |--------|--------|
183 | Click tab | Switch tab |
184 | Click panel | Focus panel + select item |
185 | Double-click track | Play immediately |
186 | `Ctrl` + drag panel border | Resize panels |
187 | Click progress bar | Seek to position |
188 | Scroll wheel | Scroll lists |
189
190 ## License
191
192 [Apache 2.0](LICENSE)