https://github.com/satvikvirmani/musicfp
A terminal based media player for programmers
https://github.com/satvikvirmani/musicfp
hactoberfest linux macos media multimedia playback playmedia python python-vlc songs videos vlc
Last synced: about 1 month ago
JSON representation
A terminal based media player for programmers
- Host: GitHub
- URL: https://github.com/satvikvirmani/musicfp
- Owner: satvikvirmani
- License: mit
- Created: 2021-05-28T13:38:13.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-10T12:57:01.000Z (8 months ago)
- Last Synced: 2025-10-28T01:29:00.745Z (7 months ago)
- Topics: hactoberfest, linux, macos, media, multimedia, playback, playmedia, python, python-vlc, songs, videos, vlc
- Language: Python
- Homepage: https://pypi.org/project/musicfp/
- Size: 153 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎵 musicfp
> A sleek, terminal-based media player built for programmers who love their command line.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/SatvikVirmani/musicfp)
---
## 🎯 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)
```bash
pip install musicfp
```
### From Source
```bash
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
```bash
# 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` | 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` | Set volume (e.g., `vol50` for 50%) |
| `quit` | Exit the player |
| `help` | Show available commands |
---
## 🎮 Examples
### Example 1: Playing a Single Song
```bash
$ 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
```bash
$ 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
```bash
$ 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](https://github.com/satvikvirmani)
- 🔗 Project: [musicfp](https://github.com/SatvikVirmani/musicfp)
---
## 🐛 Bug Reports & Feature Requests
Found a bug or have an idea for a new feature?
- **Report issues**: [GitHub Issues](https://github.com/SatvikVirmani/musicfp/issues)
- **Contribute**: Pull requests are welcome!
---
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](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](#-musicfp)**