1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
# expergo
#### An opinionated music library tool to help you manage your FLACs, compatible with the Snowsky Echo/Mini.
<img width="1920" height="1012" alt="image" src="https://github.com/user-attachments/assets/3f541f03-c4a0-4a1e-a44f-1f3f96f5ee9f" />
---
> [!IMPORTANT]
> expergo works entirely in the directory you've pointed it to. It can work off of removable storage such as the Snowsky Echo Mini, but be aware that large jobs can take some time (limited by read-write speeds).
# Echo Rules
These are the rules that the CLI applies (can be OPTIONALLY applied from the GUI):
- Recursively searches through the provided directory
- Re-samples audio higher than 192Khz 24bit via ffmpeg down to 192Khz
- Re-encodes files with block size higher than 4096 via `flac` CLI
- Rename FLAC file to `TRACK_NAME - ARTIST.flac`
- Resize embedded album art to 500x500px (good enough for small screen players, without taking up much space)
- Normalize all audio to -14 LUFS (or, with `--replaygain`, write ReplayGain tags instead and leave the audio untouched)
- Download LRC files (places them in same folder with same name, according to Snowsky Echo rules)
- A delay of 0.3 sec is hardcoded to avoid rate limit, this is a hard limit across all threads (if running multithreaded)
> [!DANGER]
> Audio normalization is DESTRUCTIVE by default! This is because some DAPs do not support the ReplyGain tag. You can toggle ReplayGain by clicking the drop down under the "Echo Rules" button.
# External Dependencies
You need the FLAC command line tool to be accessible globally, meaning it must be able to run anywhere on your machine. Using the official tool was the most consistent way of fixing the block-size issue cross-platform.
https://xiph.org/flac/download.html
- Windows: `winget install -e --id Xiph.FLAC`
- Linux: `sudo pacman -S flac` (follow your package manager)
- macOS: `brew install flac` (idk tho i don't own a mac)
All other dependencies can be installed via `uv`
```bash
uv sync
```
# CD Ripping
A bonus useful feature for ripping CDs right into expergo. Only supported on Windows and Linux.
**Linux:** Requires [abcde](https://github.com/poddmo/abcde) to be installed. Please follow distro specific instructions
**Windows:** All of the optical drive related functionalities are relegated to [CueRipper](https://github.com/gchudov/cuetools.net), expergo can automatically install this for you
# GUI
```bash
uv run expergo.py gui
```
<img width="1913" height="1038" alt="image" src="https://github.com/user-attachments/assets/192fabd5-a3bb-48f7-9b92-f90e01987352" />
<img width="1000" height="600" alt="image" src="https://github.com/user-attachments/assets/967e3a67-46a2-4abd-8c07-df56d6cea9ca" />
> [!TIP]
> If you're using a Snowsky device, you can "emulate" playlist functionality by grouping songs together via the "Genre" tag
# CLI
**Apply Echo Rules:**
```bash
uv run expergo.py <base_dir> [--nolrc] [--replaygain] [-n workers]
```
**Subcommands:**
```bash
uv run expergo.py process <base_dir> [--nolrc] [--replaygain] [-n workers]
uv run expergo.py auto-lrc <base_dir> [--force] [-n workers]
uv run expergo.py auto-cover <base_dir> [--force] [--tries N] [-n workers]
uv run expergo.py reorg <base_dir> [--artist-only] [--no-cleanup] [-n workers]
```
What each command does:
- `process`: full Echo rules pipeline (rename, resample/re-encode, normalize, resize art, optional LRC)
- `auto-lrc`: only fetch LRC files for FLACs (skips existing by default, `--force` overwrites)
- `auto-cover`: only fetch album art using MusicBrainz + Cover Art Archive, grouped per album (uses album artist when present)
- `reorg`: reorganize library into `Artist/Album/` folders, moving matching `.lrc` sidecars too
**CD Ripping is not supported from the CLI at this time**
# Other Tools
`apply_album_art.sh` - Recursively traverse all folders, automatically apply album art and resize to all FLACs that have a JPG/PNG in the same directory
|
