music-explorer 0.1.0

a side project with simple and clean music player with Tkinter GUI and Textual TUI

🎵 Music Explorer

A lightweight music player with both a graphical (Tkinter) and terminal (Textual) interface — fast to run, easy to extend.

---

Table of contents

• Features
• Quick start
• Usage
• Installation
• Configuration
• Screenshots
• Contributing
• License

---

Features

• ✅ Dual interfaces: GUI (Tkinter) and TUI (Textual)
• ✅ Supports: MP3, WAV, OGG, FLAC
• ✅ Shuffle and loop modes (Off / All / One)
• ✅ Remembers last folder, last track, and volume
• ✅ Persists playlist order to queue.json
• ⚡ Lightweight, minimal dependencies

Quick start

Recommended: run inside a virtual environment.

# run with uv (recommended)
uv run main.py

# or run directly with Python
python main.py

Usage

On startup the program offers a choice between GUI and Terminal UI. You can force a mode:

python main.py -t gui    # GUI only
python main.py -t cli    # Terminal only

Installation

Create a virtual environment and install pinned dependencies:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Configuration

Settings are saved to save.json. Example minimal defaults you can copy into save.json:

{
    "current-folder": null,
    "current-file": null,
    "settings": {
        "volume": 100,
        "shuffle": false,
        "loop": "off"
    },
    "queue-file": null
}

Playlist order is persisted to queue.json inside your music folder.

Screenshots

GUI demo

Terminal demo

Contributing

• Open issues for bugs or ideas
• Send a PR with a clear description and tests where applicable
• Keep changes small and focused

License

MIT — see the LICENSE file.

---

Made with ❤️ — happy hacking!