A powerful Python module to play and control media files with ease

• Single File Playback - Play individual audio/video files with full control
• Playlist Management - Handle multiple files as a playlist with navigation
• Complete Control - Play, pause, stop, volume control, and mute functionality
• Metadata Support - Read and edit 26+ metadata tags
• Multi-Format - Supports 8 major audio and video formats
• Pythonic API - Clean, intuitive interface with helpful return messages
• VLC Powered - Built on robust VLC media player backend

pip install playmedia

Required: VLC Media Player

Make sure VLC is installed on your system before using playmedia.

Python Packages (automatically installed):

• python-vlc - VLC Python bindings
• pretty-errors - Enhanced error formatting

from playmedia import File

# Create a player instance
player = File("path/to/song.mp3")

# Start playback
print(player.start())  # Output: Now playing Song Title

# Control playback
print(player.pause(True))  # Output: Paused
print(player.pause(False))  # Output: Resumed
print(player.set_volume(75))  # Output: Volume set to 75%
print(player.mute(True))  # Output: Muted

# View metadata
print(player.meta("Artist"))  # Output: Artist: Artist Name
print(player.meta("Album"))  # Output: Album: Album Name

# Edit metadata
print(player.edit_meta("Album", "My Custom Album"))

# Stop playback
player.stop()

from playmedia import Files

# From a directory
playlist = Files("path/to/music/folder")

# Or from a list of files
playlist = Files([
    "song1.mp3",
    "song2.mp3",
    "song3.flac"
])

# View available files
print(playlist.get_list())
# Output: {0: 'Song 1.mp3', 1: 'Song 2.mp3', 2: 'Song 3.flac'}

# Start playing from beginning
playlist.start()

# Navigate through playlist
print(playlist.next())  # Output: Now playing Song 2
print(playlist.previous())  # Output: Now playing Song 1

# Jump to specific track
print(playlist.play_at_index(2))  # Output: Now playing Song 3

# Control playback
playlist.pause(True)
playlist.set_volume(80)
playlist.mute(False)

# Get current track info
print(playlist.current_meta("Title"))
print(playlist.current_time())  # Output: {'Current time': '45.32s'}

# Stop playlist
playlist.stop()

File(path: str)

Initialize a single file player.

Files(arg: str | list)

Initialize a playlist from directory path or list of file paths.

Both classes support the following metadata tags:

Actors, Album, AlbumArtist, Artist, ArtworkURL, Copyright, Date, Description, Director, DiscNumber, DiscTotal, EncodedBy, Episode, Genre, Language, NowPlaying, Publisher, Rating, Season, Setting, ShowName, Title, TrackID, TrackNumber, TrackTotal, URL

• Audio: .m4a, .flac, .mp3, .wav, .wma, .aac
• Video: .mp4, .mkv

All control methods return descriptive strings that can be printed for user feedback:

player = File("song.mp3")
message = player.start()
print(message)  # "Now playing Song Title"

The module provides clear error messages for common issues:

try:
    player = File("nonexistent.mp3")
except FileNotFoundError as e:
    print(e)  # "No file found for the given path."

try:
    player.pause("invalid")
except TypeError as e:
    print(e)  # "The argument must be a boolean."

Always ensure a file is playing before accessing current_meta() in the Files class:

playlist = Files("music/")
playlist.start()  # Start playback first
print(playlist.current_meta("Artist"))  # Now safe to access

• Music Players: Build custom music player applications
• Media Management: Organize and play media libraries
• Automation: Script media playback for events or scheduling
• Audio Processing: Integrate playback into audio analysis workflows
• Educational Tools: Create interactive media learning applications
• Background Music: Add soundtrack capabilities to applications

• After calling stop(), the player reinitializes to prevent volume boost bugs
• current_meta() requires active playback - call start() or play_at_index() first
• VLC Media Player must be installed system-wide

Contributions, issues, and feature requests are welcome!

Feel free to check the issues page.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

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

• Email: virmanisatvik01@gmail.com
• GitHub: @satvikvirmani

Give a ⭐️ if this project helped you!

Your support motivates continued development and improvement.

• Built with python-vlc
• Powered by VLC Media Player
• Enhanced errors by pretty-errors

Made with ❤️ by Satvik Virmani