{"id":30859221,"url":"https://github.com/satvikvirmani/playmedia","last_synced_at":"2026-03-09T03:30:53.630Z","repository":{"id":38929252,"uuid":"369832651","full_name":"satvikvirmani/playmedia","owner":"satvikvirmani","description":"A powerful Python module that brings VLC media player capabilities to your code. Play, control, and manage audio/video files with a clean, Pythonic API.","archived":false,"fork":false,"pushed_at":"2025-11-08T14:53:57.000Z","size":27,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-08T16:22:52.337Z","etag":null,"topics":["audio","hacktoberfest","media","playmedia","python","python-vlc","vlc","vlc-libvlc"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/playmedia/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/satvikvirmani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-22T14:46:33.000Z","updated_at":"2025-11-08T14:54:32.000Z","dependencies_parsed_at":"2022-08-29T08:41:33.334Z","dependency_job_id":null,"html_url":"https://github.com/satvikvirmani/playmedia","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/satvikvirmani/playmedia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satvikvirmani%2Fplaymedia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satvikvirmani%2Fplaymedia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satvikvirmani%2Fplaymedia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satvikvirmani%2Fplaymedia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/satvikvirmani","download_url":"https://codeload.github.com/satvikvirmani/playmedia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satvikvirmani%2Fplaymedia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30281473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","hacktoberfest","media","playmedia","python","python-vlc","vlc","vlc-libvlc"],"created_at":"2025-09-07T14:57:38.104Z","updated_at":"2026-03-09T03:30:53.610Z","avatar_url":"https://github.com/satvikvirmani.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ch1 align=\"center\"\u003eplaymedia\u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eA powerful Python module to play and control media files with ease\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/satvikvirmani/playmedia\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Made%20by%20Satvik%20Virmani-000000?style=for-the-badge\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/satvikvirmani/playmedia?color=000000\u0026logoColor=000000\u0026style=for-the-badge\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/issues/satvikvirmani/playmedia?color=000000\u0026logoColor=000000\u0026style=for-the-badge\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/satvikvirmani/playmedia?color=000000\u0026logoColor=000000\u0026style=for-the-badge\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.0%2B-blue?style=for-the-badge\"\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n- **Single File Playback** - Play individual audio/video files with full control\n- **Playlist Management** - Handle multiple files as a playlist with navigation\n- **Complete Control** - Play, pause, stop, volume control, and mute functionality\n- **Metadata Support** - Read and edit 26+ metadata tags\n- **Multi-Format** - Supports 8 major audio and video formats\n- **Pythonic API** - Clean, intuitive interface with helpful return messages\n- **VLC Powered** - Built on robust VLC media player backend\n\n---\n\n## Installation\n\n```bash\npip install playmedia\n```\n\n### Dependencies\n\n**Required:** [VLC Media Player](https://sourceforge.net/projects/vlc/)\n\nMake sure VLC is installed on your system before using playmedia.\n\n**Python Packages** (automatically installed):\n- `python-vlc` - VLC Python bindings\n- `pretty-errors` - Enhanced error formatting\n\n---\n\n## Quick Start\n\n### Single File Playback\n\n```python\nfrom playmedia import File\n\n# Create a player instance\nplayer = File(\"path/to/song.mp3\")\n\n# Start playback\nprint(player.start())  # Output: Now playing Song Title\n\n# Control playback\nprint(player.pause(True))  # Output: Paused\nprint(player.pause(False))  # Output: Resumed\nprint(player.set_volume(75))  # Output: Volume set to 75%\nprint(player.mute(True))  # Output: Muted\n\n# View metadata\nprint(player.meta(\"Artist\"))  # Output: Artist: Artist Name\nprint(player.meta(\"Album\"))  # Output: Album: Album Name\n\n# Edit metadata\nprint(player.edit_meta(\"Album\", \"My Custom Album\"))\n\n# Stop playback\nplayer.stop()\n```\n\n### Playlist Management\n\n```python\nfrom playmedia import Files\n\n# From a directory\nplaylist = Files(\"path/to/music/folder\")\n\n# Or from a list of files\nplaylist = Files([\n    \"song1.mp3\",\n    \"song2.mp3\",\n    \"song3.flac\"\n])\n\n# View available files\nprint(playlist.get_list())\n# Output: {0: 'Song 1.mp3', 1: 'Song 2.mp3', 2: 'Song 3.flac'}\n\n# Start playing from beginning\nplaylist.start()\n\n# Navigate through playlist\nprint(playlist.next())  # Output: Now playing Song 2\nprint(playlist.previous())  # Output: Now playing Song 1\n\n# Jump to specific track\nprint(playlist.play_at_index(2))  # Output: Now playing Song 3\n\n# Control playback\nplaylist.pause(True)\nplaylist.set_volume(80)\nplaylist.mute(False)\n\n# Get current track info\nprint(playlist.current_meta(\"Title\"))\nprint(playlist.current_time())  # Output: {'Current time': '45.32s'}\n\n# Stop playlist\nplaylist.stop()\n```\n\n---\n\n## API Reference\n\n### File Class\n\n**`File(path: str)`**\n\nInitialize a single file player.\n\n#### Methods\n\n| Method | Parameters | Returns | Description |\n|--------|-----------|---------|-------------|\n| `start()` | None | `str` | Starts playback |\n| `pause(status)` | `status: bool` | `str` | Pauses (True) or resumes (False) |\n| `mute(status)` | `status: bool` | `str` | Mutes (True) or unmutes (False) |\n| `set_volume(vol)` | `vol: int` (0-100) | `str` | Sets volume level |\n| `meta(tag)` | `tag: str` | `str` | Retrieves metadata |\n| `edit_meta(tag, value)` | `tag: str, value: str` | `str` | Edits metadata |\n| `stop()` | None | `None` | Stops playback |\n\n### Files Class\n\n**`Files(arg: str | list)`**\n\nInitialize a playlist from directory path or list of file paths.\n\n#### Methods\n\n| Method | Parameters | Returns | Description |\n|--------|-----------|---------|-------------|\n| `get_list()` | None | `dict` | Returns indexed file dictionary |\n| `start()` | None | `dict` | Starts sequential playback |\n| `play_at_index(index)` | `index: int` | `str` | Plays file at index |\n| `pause(status)` | `status: bool` | `str` | Pauses or resumes |\n| `next()` | None | `str` | Skips to next track |\n| `previous()` | None | `str` | Returns to previous track |\n| `mute(status)` | `status: bool` | `str` | Mutes or unmutes |\n| `set_volume(vol)` | `vol: int` (0-100) | `str` | Sets volume level |\n| `current_meta(tag)` | `tag: str` | `str` | Gets current track metadata |\n| `current_time()` | None | `dict` | Gets current playback time |\n| `stop()` | None | `None` | Stops playlist |\n\n---\n\n## Supported Metadata Tags\n\nBoth classes support the following metadata tags:\n\n`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`\n\n---\n\n## Supported File Formats\n\n- **Audio:** `.m4a`, `.flac`, `.mp3`, `.wav`, `.wma`, `.aac`\n- **Video:** `.mp4`, `.mkv`\n\n---\n\n## Usage Tips\n\n### Return Values\n\nAll control methods return descriptive strings that can be printed for user feedback:\n\n```python\nplayer = File(\"song.mp3\")\nmessage = player.start()\nprint(message)  # \"Now playing Song Title\"\n```\n\n### Error Handling\n\nThe module provides clear error messages for common issues:\n\n```python\ntry:\n    player = File(\"nonexistent.mp3\")\nexcept FileNotFoundError as e:\n    print(e)  # \"No file found for the given path.\"\n\ntry:\n    player.pause(\"invalid\")\nexcept TypeError as e:\n    print(e)  # \"The argument must be a boolean.\"\n```\n\n### Metadata Access\n\nAlways ensure a file is playing before accessing `current_meta()` in the Files class:\n\n```python\nplaylist = Files(\"music/\")\nplaylist.start()  # Start playback first\nprint(playlist.current_meta(\"Artist\"))  # Now safe to access\n```\n\n---\n\n## Use Cases\n\n- **Music Players:** Build custom music player applications\n- **Media Management:** Organize and play media libraries\n- **Automation:** Script media playback for events or scheduling\n- **Audio Processing:** Integrate playback into audio analysis workflows\n- **Educational Tools:** Create interactive media learning applications\n- **Background Music:** Add soundtrack capabilities to applications\n\n---\n\n## Known Issues \u0026 Notes\n\n- After calling `stop()`, the player reinitializes to prevent volume boost bugs\n- `current_meta()` requires active playback - call `start()` or `play_at_index()` first\n- VLC Media Player must be installed system-wide\n\n---\n\n## Contributing\n\nContributions, issues, and feature requests are welcome!\n\nFeel free to check the [issues page](https://github.com/satvikvirmani/playmedia/issues).\n\n### How to Contribute\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n---\n\n## License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Author\n\n### **Satvik Virmani**\n\n\u003ca href=\"https://twitter.com/satvikvirmani\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/follow/satvikvirmani?color=000000\u0026logo=twitter\u0026logoColor=FFFFFF\u0026style=for-the-badge\"\u003e\n\u003c/a\u003e\n\n- **Email:** virmanisatvik01@gmail.com\n- **GitHub:** [@satvikvirmani](https://github.com/satvikvirmani)\n\n---\n\n## Show Your Support\n\nGive a ⭐️ if this project helped you!\n\nYour support motivates continued development and improvement.\n\n---\n\n## Acknowledgments\n\n- Built with [python-vlc](https://github.com/oaubert/python-vlc)\n- Powered by [VLC Media Player](https://www.videolan.org/vlc/)\n- Enhanced errors by [pretty-errors](https://github.com/onelivesleft/PrettyErrors)\n\n---\n\n\u003cp align=\"center\"\u003e\n    Made with ❤️ by Satvik Virmani\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatvikvirmani%2Fplaymedia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatvikvirmani%2Fplaymedia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatvikvirmani%2Fplaymedia/lists"}