antarctiteex-mp3-player
A terminal interface for playing and organizing a folder of MP3 files.
Features
- Local MP3 Playback
- Automatic Lyrics Sidebar with Embedded-Tag and LRCLIB Lookup
- Library Search and Filtering
- Playlist Creation, Renaming, and Deletion
- Automatic Artist-Tag Playlists with Manual Drag-and-Drop Fallback
- Optional Artist-Tag Display in the MP3 List
- Drag-and-Drop Playlist Management
- Shift-Click Range Selection and Multi-Song Actions
- Loop and Weighted Shuffle Playback
- Play Count, Listening Time, Duration, and Last-Played Tracking
- Library Sorting by Name, Play Time, Plays, Duration, or Last Played
- YouTube Search and Preview
- YouTube Audio Downloads with Pre-Save Renaming and Live Progress
- YouTube Sorting by Title, Channel, Views, or Likes
- Apple Music Radio with an Upward-Opening Station Menu (macOS)
- Play, Pause, Seek, and Volume Controls
- Paused Session Restore for the Last Song, Position, Volume, Playlist, and Mode
- One-Click Library Refresh for Files Added or Removed Outside the App
- Automatic Per-Song Volume Normalization
- Keyboard, Mouse, and Media-Key Controls
- Compact In-App Control Reference
- In-App Success, Warning, and Error Notifications
- Detailed MP3 Playback-Failure Notifications
- MP3 Renaming and Trash-Safe Deletion
- Multi-Song Selection and Bulk Actions
- Automatic Pause for Screen Lock and Find My Alerts (macOS)
- Non-Speaker Safety Mode (macOS)
- MP3 Filename Export
- Responsive Terminal Interface
- Unified Song, Playlist, and Analysis Cache
Install
Install the player from PyPI:
python3 -m pip install antarctiteex-mp3-player
Then open a music folder and launch the player:
cd /path/to/music
antarctiteex
You can also pass the music folder directly:
antarctiteex /path/to/music
The mp3-player command is also available as an alias.
The player stores song metadata, playlists, settings, and analysis in a single
.mp3cache.json file inside the selected music folder.
Lyrics
Click the vertical Lyrics tab beside the song list to open the scrollable
sidebar. Lyrics are looked up only while that sidebar is open. The player
searches Genius for a verified song and artist, then reads the lyrics
from its song page. If that fails, it tries lyrics embedded in the MP3 and
then LRCLIB. Genius's official API returns song metadata and page URLs, not
lyrics text. Set GENIUS_ACCESS_TOKEN to a Genius API client access token to
use its official search endpoint; without a token, the player uses Genius's
public website search. Successful results are saved in .mp3cache.json, so
replaying a song does not make another network request. Section headings
supplied by the source, such as [Verse], [Chorus], and [Bridge], remain
visible. When a section credits singers by name, each name gets a distinct
color. Genius italic markup is used to color different singers' lines; in a
two-singer section without an italicized name credit, italic lines are assigned
to the second listed singer. Lyrics are censored with better-profanity,
including disguised words such as s*x, s✱x, and s*xy; "hell" and "God"
stay visible.
Drag the sidebar's left edge to resize it. Playlist and lyrics widths are saved
in .mp3cache.json and restored the next time you open the player. Resizing
lyrics leaves the playlist width alone.
Accurate artist and title metadata gives the best matches. The player reads
MP3 tags first. If those are missing, use [Artist] Song Title.mp3 or
Artist - Song Title.mp3. Close the sidebar with its × button or the
vertical Lyrics tab.
For abbreviated artist tags, an artist-named playlist with the same tag can
identify the artist. If no playlist exists, the player can infer the artist
from a clearer song with the same tag, such as using [AG] 7 rings to identify
[AG] freak. Verified artist hints are saved in .mp3cache.json for later songs.
Artist Tags and Automatic Playlists
Artist tags are short labels at the very beginning of an MP3 filename. Put the tag in square brackets, followed by the song title:
[OR] vampire.mp3
[OR] drivers license.mp3
[21P] Stressed Out.mp3
To make an automatic playlist, create a playlist, right-click it, choose
Edit tag, and enter only the text inside the brackets. For example, enter
OR, not [OR]. The player then fills that playlist with every MP3 whose
filename begins with [OR]. Matching is case-insensitive, so [or] also
matches. The tag must be at the start of the filename.
A tagged playlist updates automatically when matching MP3 files are added, renamed, or removed. Because its contents come from filenames, individual songs cannot be dragged into or removed from a tagged playlist. Clear the playlist's tag to turn it back into a manual playlist that accepts drag-and-drop songs.
Playlist names do not display their assigned tags in the sidebar. The Show Tags control only changes how MP3 names appear in the song list; it does not rename files or affect automatic playlist matching.
For lyrics, the bracketed tag is checked against the artist's initials before
online results are used. Numbers can stand for their spelled-out words: [21P]
matches Twenty One Pilots (TOP). Naming a tagged playlist after the artist
can also help the search find the right song. The lyrics search tries the
number as English words too, so [21P] also searches with twenty one P.
ffmpeg and ffprobe must be available on PATH for audio conversion and
analysis features. On macOS, install them with brew install ffmpeg.
Development
Run the test suite with:
python3 -m unittest test_play.py
1 maintainer
Metadata
1 maintainer
Release files for antarctiteex-mp3-player 0.1.68
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| antarctiteex_mp3_player-0.1.68.tar.gz | 83.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| antarctiteex_mp3_player-0.1.68-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 169.4 kB
Release files / antarctiteex_mp3_player-0.1.68.tar.gz
| Download URL | antarctiteex_mp3_player-0.1.68.tar.gz |
|---|---|
| Size | 83.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd922c09f901ef5023f1dbf0b30376183dc9dededcefc8a83387df1e51374c47
|
|
BLAKE2b-256 checksum How to use checksums |
de77675a4d6b88b0438f2d3224134ef011139742a3968226c769d2956b1c00d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / antarctiteex_mp3_player-0.1.68-py3-none-any.whl
| Download URL | antarctiteex_mp3_player-0.1.68-py3-none-any.whl |
|---|---|
| Size | 85.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0ebe660dd53c952b887d461d0305394742499f9a545b2b42871bb388cb3aad21
|
|
BLAKE2b-256 checksum How to use checksums |
9995f6079e215d26a917c048e96e28d10193c4f7192feb0620854321ca595492
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
