Metadata-Version: 2.4
Name: antarctiteex-mp3-player
Version: 0.1.71
Summary: A terminal MP3 player with playlists, lyrics, YouTube tools, and Apple Music radio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: better-profanity<0.8,>=0.7
Requires-Dist: pygame>=2.5
Requires-Dist: pynput>=1.7
Requires-Dist: Send2Trash>=1.8
Requires-Dist: textual>=0.50
Requires-Dist: yt-dlp

# 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)
- Event-Driven Non-Speaker Safety Mode (macOS)
- MP3 Filename Export
- Responsive Terminal Interface
- Unified Song, Playlist, and Analysis Cache

## Install

Install the player from PyPI:

```sh
python3 -m pip install antarctiteex-mp3-player
```

Then open a music folder and launch the player:

```sh
cd /path/to/music
antarctiteex
```

You can also pass the music folder directly:

```sh
antarctiteex /path/to/music
```

The `mp3-player` command is also available as an alias.

On macOS, Non-Speaker Mode listens for output-device changes through CoreAudio
and uses `SwitchAudioSource` to identify the new output. It pauses playback as
soon as the output changes, then resumes it if the new output is safe.

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. The singer with the most solo lines keeps the normal text color;
other credited singers get distinct colors. In a duet, Genius italic markup
is used to color only the words attributed to an added singer, including
their part of a shared line. If the markup does not identify which words
belong to whom, the lyrics stay in the normal color. 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:

```text
[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:

```sh
python3 -m unittest test_play.py
```
