retro-amp

Terminal-Musikplayer mit Retro-Charme — geschrieben in Python mit Textual.

A terminal music player with retro charm — built with Python and Textual.

BeOS Theme — Ordner-Browser, Datei-Tabelle, Lyrics, Spektral-Visualizer

IBM Terminal — Phosphor-Gruen	Amiga Workbench — Blau/Orange

C64 Theme — YouTube-Links	Lyrics — Original (Englisch)

Installation

One-Click Installer

Keine Abhaengigkeiten noetig — kein Python, kein Git. / No dependencies needed — no Python, no Git.

Linux / macOS:

curl -fsSL https://github.com/michaelblaess/retro-amp/releases/latest/download/install.sh | bash

Windows (PowerShell als Administrator):

irm https://github.com/michaelblaess/retro-amp/releases/latest/download/install.ps1 | iex

Installationspfade / Installation Paths

Manuell / Manual (Python >= 3.12)

pip install git+https://github.com/michaelblaess/retro-amp.git
retro-amp

Aus Quellcode / From Source

git clone https://github.com/michaelblaess/retro-amp.git
cd retro-amp
python -m venv .venv
.venv/Scripts/activate      # Windows
# source .venv/bin/activate  # Linux/macOS
pip install -e ".[dev]"
retro-amp

Benutzung / Usage

retro-amp                     # Startet mit Standard-Musikordner / Start with default music folder
retro-amp /pfad/zur/musik     # Startet in einem bestimmten Ordner / Start in specific folder
retro-amp --lang en           # Startet mit englischer Oberflaeche / Start with English UI
retro-amp --version           # Zeigt die Version / Show version

Features

• Ordner-Browser — Linkes Panel mit Verzeichnisbaum, filtert Audio-Dateien automatisch
• Favoriten-Ansicht — Alle Favoriten als Baumstruktur, mit TAB umschalten
• Playlist-Ansicht — Playlists als Baumstruktur, Songs direkt abspielen oder entfernen
• Datei-Tabelle — Rechtes Panel mit Name, Format, Bitrate, Dauer (via mutagen)
• Audio-Playback — MP3, OGG/Opus, FLAC, WAV, MOD/XM/S3M, SID (via pygame.mixer + pyogg)
• Spektral-Visualizer — Echte FFT-Analyse, 32 Frequenzbaender, Spektralfarben, Peak-Hold-Effekt
• Liner Notes — Wikipedia-Info zum aktuellen Artist (Taste I), automatisch gecached
• Globale Suche — Dateien in der gesamten Bibliothek suchen (Taste S)
• Playlists — Als Markdown-Dateien gespeichert, Standard-Playlist "Favoriten"
• 6 Retro-Themes — C64, Amiga Workbench, Atari ST GEM, IBM Terminal, NeXTSTEP, BeOS
• Mehrsprachig — Deutsch (Standard) und Englisch, umschaltbar via --lang
• Debug-Log — Ausfuehrliches Log mit Artist/Titel, Pfaden, Events (Taste O)
• Dateiverwaltung — Umbenennen (U) und Loeschen (DEL) direkt aus dem Player
• Settings-Persistenz — Lautstaerke, letzter Ordner, Theme, Sprache werden gespeichert

Tastenbelegung / Keybindings

Themes

Mit T durch die Themes wechseln. / Press T to cycle through themes.

Die Themes sind als eigenstaendiges Paket verfuegbar: textual-themes

Spektral-Visualizer

• Echte FFT-basierte Analyse (stdlib cmath, kein numpy)
• 2048-Punkt-FFT mit Hann-Fenster
• 32 log-skalierte Frequenzbaender (20 Hz – 18 kHz)
• Spektralfarben: Rot (Bass) → Gelb → Gruen → Cyan → Blau (Hoehen)
• Peak-Hold mit fallendem Effekt
• 3-zeilige Multi-Row-Darstellung (24 Hoehenstufen)
• PCM-Laden im Hintergrund-Thread

Playlists

Playlists werden als Markdown-Dateien in ~/.retro-amp/playlists/ gespeichert:

# Favoriten

- D:\Dropbox\MUSIK\Kraftwerk\autobahn.mp3
- D:\Dropbox\MUSIK\C64\last_ninja.sid

• F — Song zu Favoriten hinzufuegen/entfernen
• P — Playlist-Menue: neue erstellen, bestehende laden, Song hinzufuegen

Architektur / Architecture

Clean Architecture mit strikter Dependency Rule:

src/retro_amp/
├── domain/           # Models, Protocols — keine externen Imports
│   ├── models.py     #   AudioTrack, PlayerState, Playlist
│   └── protocols.py  #   AudioPlayer, MetadataReader, PlaylistRepository
├── services/         # Business-Logik — importiert nur domain/
│   ├── player_service.py
│   ├── playlist_service.py
│   └── metadata_service.py
├── infrastructure/   # Implementierungen — pygame, mutagen, JSON
│   ├── audio_player.py   # PygameAudioPlayer
│   ├── spectrum.py        # SpectrumAnalyzer (FFT)
│   ├── metadata_reader.py # MutagenMetadataReader
│   ├── playlist_store.py  # MarkdownPlaylistStore
│   └── settings.py        # JsonSettingsStore
├── widgets/          # Textual Widgets
├── screens/          # Textual ModalScreens
├── i18n.py           # Internationalisierung (de/en)
├── locale/           # JSON-Sprachpakete (de.json, en.json)
├── themes.py         # Re-Export aus textual-themes
└── app.py            # Composition Root

Entwicklung / Development

# Setup
git clone https://github.com/michaelblaess/retro-amp.git
cd retro-amp
python -m venv .venv
.venv/Scripts/activate      # Windows
pip install -e ".[dev]"

# Tests
pytest

# Type-Check
mypy src/

# Lokaler Build / Local Build (Standalone EXE)
pip install pyinstaller
pyinstaller retro-amp.spec --noconfirm

Release erstellen / Create Release

git tag v0.4.0
git push origin v0.4.0
# GitHub Actions baut automatisch Windows/macOS/Linux Installer

Tech-Stack

Lizenz / License

Apache License 2.0 — siehe LICENSE.

Autor / Author

Michael Blaess — GitHub