Skip to content

Commit a3a4aad

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent 3b6bbb3 commit a3a4aad

2 files changed

Lines changed: 245 additions & 0 deletions

File tree

‎assets/commands/cliamp.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# TAGLINE
2+
3+
Retro terminal music player inspired by Winamp 2.x
4+
5+
# TLDR
6+
7+
**Play all audio files** in a directory recursively
8+
9+
```cliamp ~/Music```
10+
11+
**Play specific files** by format
12+
13+
```cliamp *.mp3 *.flac *.wav *.ogg```
14+
15+
**Play with shuffle** and custom volume
16+
17+
```cliamp --shuffle --volume -5 [path/to/music]```
18+
19+
**Stream audio** from a URL
20+
21+
```cliamp [https://example.com/song.mp3]```
22+
23+
**Play an M3U playlist**
24+
25+
```cliamp [path/to/playlist.m3u]```
26+
27+
**Play a podcast** from an RSS feed
28+
29+
```cliamp [https://example.com/podcast/feed.xml]```
30+
31+
# SYNOPSIS
32+
33+
**cliamp** [_options_] [_files/directories/URLs_]
34+
35+
# PARAMETERS
36+
37+
**--volume** _dB_
38+
> Volume in dB, range -30 to +6. Default 0.
39+
40+
**--shuffle**
41+
> Enable shuffle mode.
42+
43+
**--repeat** _mode_
44+
> Set repeat mode: **off**, **all**, or **one**. Default off.
45+
46+
**--mono** / **--no-mono**
47+
> Enable or disable mono output (L+R downmix).
48+
49+
**--auto-play**
50+
> Start playback immediately.
51+
52+
**--theme** _name_
53+
> Set UI theme by name.
54+
55+
**--eq-preset** _name_
56+
> Set EQ preset: **Flat**, **Rock**, **Pop**, **Jazz**, **Classical**, **Bass Boost**, **Treble Boost**, **Vocal**, **Electronic**, **Acoustic**.
57+
58+
**--sample-rate** _Hz_
59+
> Output sample rate: 22050, 44100, 48000, 96000, 192000. Default 44100.
60+
61+
**--buffer-ms** _ms_
62+
> Speaker buffer in milliseconds, range 50-500. Default 100.
63+
64+
**--resample-quality** _n_
65+
> Resample quality factor, range 1-4. Default 4.
66+
67+
**-h**, **--help**
68+
> Show help and exit.
69+
70+
**-v**, **--version**
71+
> Print version and exit.
72+
73+
**--upgrade**
74+
> Update to the latest release.
75+
76+
# DESCRIPTION
77+
78+
**cliamp** is a retro terminal music player inspired by Winamp 2.x. It plays **MP3**, **WAV**, **FLAC**, **OGG**, **AAC**, **ALAC**, **Opus**, and **WMA** with a 10-band spectrum visualizer, 10-band parametric EQ, and playlist management.
79+
80+
It supports local files, directories (recursive scanning), HTTP streaming, M3U/M3U8 playlists, podcast RSS feeds, and URLs from YouTube, SoundCloud, and Bandcamp (via yt-dlp). A built-in file browser and playlist manager allow organizing music from within the terminal.
81+
82+
cliamp can also connect to a Navidrome server for remote music streaming via environment variables.
83+
84+
# KEYBOARD CONTROLS
85+
86+
```
87+
Space Play / Pause
88+
s Stop
89+
> . Next track
90+
< , Previous track
91+
Left/Right Seek -/+5s
92+
+ - Volume up/down
93+
m Toggle mono
94+
Tab Toggle focus (Playlist / EQ)
95+
j k Playlist scroll / EQ band adjust
96+
h l EQ cursor left/right
97+
Enter Play selected track
98+
e Cycle EQ preset
99+
t Choose theme
100+
v Cycle visualizer
101+
V Full-screen visualizer
102+
S Save track to ~/Music
103+
/ Search playlist
104+
x Expand/collapse playlist
105+
o Open file browser
106+
a Toggle queue (play next)
107+
A Queue manager
108+
p Playlist manager
109+
r Cycle repeat (Off / All / One)
110+
z Toggle shuffle
111+
Ctrl+K Show keymap
112+
b Esc Back to provider
113+
q Quit
114+
```
115+
116+
# CONFIGURATION
117+
118+
Configuration is stored in **~/.config/cliamp/config.toml**:
119+
120+
```
121+
# Default volume in dB (range: -30 to 6)
122+
volume = 0
123+
124+
# Repeat mode: "off", "all", or "one"
125+
repeat = "off"
126+
127+
# Start with shuffle enabled
128+
shuffle = false
129+
130+
# Start with mono output (L+R downmix)
131+
mono = false
132+
133+
# EQ preset: "Flat", "Rock", "Pop", "Jazz", "Classical",
134+
# "Bass Boost", "Treble Boost", "Vocal", "Electronic", "Acoustic"
135+
eq_preset = "Flat"
136+
137+
# 10-band EQ gains in dB (range: -12 to 12)
138+
# Bands: 70Hz, 180Hz, 320Hz, 600Hz, 1kHz, 3kHz, 6kHz, 12kHz, 14kHz, 16kHz
139+
eq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
140+
```
141+
142+
Custom playlists can be created as **.toml** files in **~/.config/cliamp/playlists/**. Running **cliamp** without arguments opens the playlist browser.
143+
144+
# CAVEATS
145+
146+
AAC, ALAC (.m4a), Opus, and WMA playback requires **ffmpeg** installed. MP3, WAV, FLAC, and OGG work without ffmpeg. YouTube/SoundCloud/Bandcamp support requires **yt-dlp**. Non-seekable HTTP streams display a static seek bar with seek keys silently ignored.
147+
148+
# HISTORY
149+
150+
**cliamp** is a terminal music player written in **Go** by developer **bjarneo** (iamdothash), inspired by **Winamp 2.x**. It is built with the **Bubbletea** TUI framework, **Lip Gloss** for styling, and **Beep** for audio playback.
151+
152+
# SEE ALSO
153+
154+
[mpv](/man/mpv)(1), [ffmpeg](/man/ffmpeg)(1), [ffplay](/man/ffplay)(1)

‎assets/commands/zformat.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# TAGLINE
2+
3+
Zsh string formatting and alignment builtin
4+
5+
# TLDR
6+
7+
**Format a string** with named specifiers
8+
9+
```zformat -f REPLY "Name: %n, Age: %a" n:Alice a:30```
10+
11+
**Format with field width** padding and truncation
12+
13+
```zformat -f REPLY "%-20n %5a" n:Alice a:30```
14+
15+
**Use ternary expressions** to conditionally output text
16+
17+
```zformat -f REPLY "Status: %(s.active.inactive)" s:1```
18+
19+
**Align strings** into columns with a separator
20+
21+
```zformat -a result " = " "key1:value1" "key2:value2" "longkey:value3"```
22+
23+
**Format with existence-based** ternary (non-empty test)
24+
25+
```zformat -F REPLY "%(n.Name: %n.anonymous)" n:Alice```
26+
27+
# SYNOPSIS
28+
29+
**zformat** **-f** _param_ _format_ _spec_ ...
30+
**zformat** **-F** _param_ _format_ _spec_ ...
31+
**zformat** **-a** _array_ _sep_ _spec_ ...
32+
33+
# PARAMETERS
34+
35+
**-f** _param_ _format_ _spec_ ...
36+
> Format a string. Each _spec_ is **char:string**. Every **%char** in _format_ is replaced by the corresponding _string_. The result is stored in _param_. Supports field widths and ternary expressions with numeric comparison.
37+
38+
**-F** _param_ _format_ _spec_ ...
39+
> Like **-f**, but ternary expressions choose between true/false text based on whether the format specifier is **present and non-empty**, rather than numeric comparison.
40+
41+
**-a** _array_ _sep_ _spec_ ...
42+
> Align strings. Each _spec_ is **left:right**. The colon is replaced by _sep_ and left strings are padded with spaces so all separators align vertically. Result is stored in _array_.
43+
44+
# DESCRIPTION
45+
46+
**zformat** is a builtin command provided by the **zsh/zutil** module. It performs string formatting and alignment operations commonly used in zsh completion system internals and custom scripts.
47+
48+
The **-f** form replaces **%char** sequences in a format string with values from named specifiers. Each specifier is a single character followed by a colon and a value string. Optional minimum and maximum field widths can be specified as **%min.maxc** where negative minimum widths pad to the left. Ternary expressions in the form **%(X.true_text.false_text)** compare the specifier value numerically against a test number (default 0).
49+
50+
The **-F** form works identically except ternary expressions test whether the specifier value is present and non-empty rather than performing numeric comparison.
51+
52+
The **-a** form aligns a list of **left:right** string pairs by padding the left portions with spaces so that the separator strings all line up when displayed vertically. This is useful for formatting option lists and help text.
53+
54+
The module must be loaded before use with **zmodload zsh/zutil**.
55+
56+
# FIELD WIDTH
57+
58+
Format specifiers support **%min.maxc** notation:
59+
60+
**%20n** pads with spaces to the right to minimum width 20
61+
**%-20n** pads with spaces to the left to minimum width 20
62+
**%.10n** truncates after 10 characters
63+
**%20.30n** pads to 20, truncates at 30
64+
**%12.12i** displays exactly 12 characters (useful for truncating hashes)
65+
66+
# TERNARY EXPRESSIONS
67+
68+
With **-f**, ternary expressions use numeric comparison:
69+
70+
**%(X.true.false)** outputs true if X equals 0 (default test number)
71+
**%3(X.true.false)** outputs true if X equals 3
72+
**%-1(X.true.false)** outputs true if X equals -1
73+
74+
With **-F**, ternary expressions test presence:
75+
76+
**%(X.true.false)** outputs true if X is present and non-empty
77+
A test number with **-F** indicates minimum width for the value
78+
79+
Ternary expressions can be nested and the delimiter character after the specifier is arbitrary (not limited to dot).
80+
81+
# CAVEATS
82+
83+
**zformat** requires the **zsh/zutil** module to be loaded first with **zmodload zsh/zutil**. It is zsh-specific and not available in other shells. The single-character specifier limit means only 62 unique format variables (a-z, A-Z, 0-9) are available per format string. Ternary expression delimiters must not conflict with the specifier values.
84+
85+
# HISTORY
86+
87+
**zformat** was introduced as part of the **zsh/zutil** module in **zsh 4.0** (2001). It was designed primarily to support the zsh completion system's formatting needs, particularly the **zstyle** based configuration and **vcs_info** version control status displays. The **-F** option for existence-based ternary testing was added later to complement the numeric comparison of **-f**.
88+
89+
# SEE ALSO
90+
91+
[zsh](/man/zsh)(1), [zstyle](/man/zstyle)(1), [zmodload](/man/zmodload)(1), [zparseopts](/man/zparseopts)(1)

0 commit comments

Comments
 (0)