🎵 musicfp

A sleek, terminal-based media player built for programmers who love their command line.

---

🎯 What is musicfp?

musicfp (music for programmers) is a powerful yet minimalist media player that lives entirely in your terminal. No GUI bloat, no unnecessary features—just pure, efficient audio playback controlled by simple commands. Perfect for developers who want to stay in the terminal while enjoying their favorite music.

✨ Features

• 🎼 Dual Playback Modes - Play single files or entire directories
• 🔀 Shuffle Support - Randomize your playlist with a simple flag
• 🎚️ Real-time Volume Control - Adjust volume on the fly
• ⏯️ Complete Playback Controls - Pause, skip, next, previous, and more
• 🧵 Multi-threaded Architecture - Responsive controls that don't block playback
• 📊 Metadata Display - See song and album information for single files
• 🎭 Wide Format Support - Supports MP3, FLAC, M4A, MP4, WAV, WMA, AAC, and MKV
• 💻 Terminal-native - Stay productive without leaving your workflow

---

🚀 Installation

Using pip (Recommended)

pip install musicfp

From Source

git clone https://github.com/SatvikVirmani/musicfp.git
cd musicfp
pip install -e .

Requirements

• Python 3.0 or higher
• python-vlc library (automatically installed)

---

📖 Usage

Basic Commands

# Play a single audio file
musicfp /path/to/song.mp3

# Play all songs in a directory
musicfp /path/to/music/folder

# Play with shuffle enabled
musicfp /path/to/music/folder --shuffle
# or
musicfp /path/to/music/folder -s

# Play all songs in current directory
musicfp current

In-Player Commands

When Playing a Single File

Command	Description
skip	Skip the current song
pause	Pause playback
resume	Resume playback
repeat	Restart the current song
vol<number>	Set volume (e.g., vol75 for 75%)
quit	Exit the player
help	Show available commands

When Playing Multiple Files (Directory)

Command	Description
pause	Pause/resume playback
next	Play next song
previous	Play previous song
vol<number>	Set volume (e.g., vol50 for 50%)
quit	Exit the player
help	Show available commands

---

🎮 Examples

Example 1: Playing a Single Song

$ musicfp ~/Music/favorite-song.mp3
Playing "Favorite Song" from "Best Album"
>>  vol80
Volume set to 80%
>>  pause
Paused
>>  resume
Resumed
>>  quit

Example 2: Playing a Directory with Shuffle

$ musicfp ~/Music/Playlist --shuffle
Playing all songs from directory: /home/user/Music/Playlist with shuffle ON
>>  next
>>  vol60
Volume set to 60%
>>  quit

Example 3: Quick Play from Current Directory

$ cd ~/Music/WorkoutMix
$ musicfp current -s
Playing all songs from directory: /home/user/Music/WorkoutMix with shuffle ON
>>  

---

🎨 Supported Formats

musicfp supports a wide range of audio and video formats:

• Audio: MP3, FLAC, M4A, WAV, WMA, AAC
• Video: MP4, MKV (audio extraction)

---

🏗️ Project Structure

musicfp/
├── LICENSE                 # MIT License
├── pyproject.toml         # Build configuration
├── setup.py               # Package setup
├── README.md              # This file
└── src/
    └── musicfp/
        ├── __init__.py    # Package initializer
        └── __main__.py    # Main application logic

---

🔧 How It Works

musicfp uses a multi-threaded architecture to provide responsive controls:

1. Playback Thread - Handles media loading and playback using VLC
2. Input Thread - Listens for user commands without blocking playback

The application leverages python-vlc, Python bindings for the powerful VLC media player, ensuring robust and reliable playback across all supported formats.

---

👨‍💻 About the Author

Satvik Virmani

• 📧 Email: virmanisatvik01@gmail.com
• 🐙 GitHub: @satvikvirmani
• 🔗 Project: musicfp

---

🐛 Bug Reports & Feature Requests

Found a bug or have an idea for a new feature?

• Report issues: GitHub Issues
• Contribute: Pull requests are welcome!

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

---

🌟 Show Your Support

If you find musicfp useful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing it with fellow developers
• 🍴 Forking and contributing improvements

---

💡 Why musicfp?

As developers, we spend countless hours in the terminal. Why switch contexts just to control music? musicfp keeps you in your flow state, letting you control your soundtrack with the same efficiency you bring to your code.

Stay in the terminal. Stay productive. Stay in the zone.

---

Made with ❤️ by Satvik Virmani

⬆ back to top