{"id":17912725,"url":"https://github.com/stypox/mp3-player","last_synced_at":"2026-02-22T16:06:58.224Z","repository":{"id":128744220,"uuid":"131479664","full_name":"Stypox/mp3-player","owner":"Stypox","description":"Plays playlists of mp3s in the desired order (track number, title...)","archived":false,"fork":false,"pushed_at":"2025-01-06T14:13:40.000Z","size":69,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-29T07:38:39.663Z","etag":null,"topics":["audio","audio-player","id3","id3-reader","metadata","mp3","mp3-player","mp3-tags","mp3player","music","music-metadata","music-player","music-sorting","player"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stypox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-04-29T08:55:14.000Z","updated_at":"2025-02-21T15:50:21.000Z","dependencies_parsed_at":"2025-10-29T07:31:28.341Z","dependency_job_id":"d31164bb-9b94-40e8-b87a-4005e9d96b2b","html_url":"https://github.com/Stypox/mp3-player","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Stypox/mp3-player","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Fmp3-player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Fmp3-player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Fmp3-player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Fmp3-player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stypox","download_url":"https://codeload.github.com/Stypox/mp3-player/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Fmp3-player/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29717902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"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","audio-player","id3","id3-reader","metadata","mp3","mp3-player","mp3-tags","mp3player","music","music-metadata","music-player","music-sorting","player"],"created_at":"2024-10-28T19:46:43.645Z","updated_at":"2026-02-22T16:06:58.173Z","avatar_url":"https://github.com/Stypox.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mp3 player\nPlays playlists of MP3s **sorted** by **track number**, by title, **randomly**... **Remembers the song being played** and the sorting settings before exiting. Can be controlled by pressing **keyboard keys**.\n##### Useful in combination with my youtube [playlist-downloader](https://github.com/Stypox/song-downloader) that saves song metadata.\n\n# Keyboard controls\nThe script uses **keyboard input**, instead of console input, since it's **simpler** and more **convenient**. Note that the console window must be focused for this to work. For example by pressing ``p`` the music pauses. This is the complete list of **keybindings** (**\\|** means or):\n\n\tAbort without saving:                              a | e\n\tSave current song and sorting settings, then exit: s\n\tPause and resume:                                  p | Enter\n\tRestart: ......................................... r | Home (*)\n\tNext song:                                         Arrow down | Arrow right\n\tPrevious song: ................................... Arrow up | Arrow left\n\tNext playlist:                                     Page up\n\tPrevious playlist: ............................... Page down\n\nIn case the used console doesn't support direct keyboard input, **press Enter** after pressing a key, just like it was a normal console input.  \n(*) ``Home`` is also known as ``Start`` or ``Beginning``, depending on the keyboard.\n\n# Sorting\nThe script provides several ways to **sort songs** and uses [ID3 metadata](https://en.wikipedia.org/wiki/ID3) to get informations about MP3s. The **default** sort order is by **track number** and all sort orders have a **corresponding code** that the script uses to understand them (see [Usage](#usage)):\n* **Path**: sorts the songs based on their path in alphabetical order a-z \n(codes: \"p\" or \"path\")\n* **Title**: sorts the songs based on their title in alphabetical order a-z \n(codes: \"t\" or \"title\")\n* **Artist**: sorts the songs based on their artist in alphabetical order a-z \n(codes: \"a\" or \"artist\")\n* **Track number**: sorts the songs based on their track number from bottom up \n(codes: \"n\" or \"number\" or \"tracknumber\")\n* **Random**: randomly shuffles all the songs \n(codes: \"r\" or \"random\")\n* **Modified** (prefix): after sorting the songs as requested, this modifier introduces some small variability\n(prefix codes: \"m-\" or \"modified-\")\n* **Distributed** (prefix): after sorting the songs as requested, this modifier shuffles the songs according to a probability distribution that picks one song at a time preferring songs that come first in the sorted list but still picking later songs often enough\n(prefix codes: \"d-\" or \"distributed-\")\n\nFor example: \"p\" -\u003e sorted by path; \"m-number\" -\u003e sorted by track number with some variability;\n\n\n# Usage\nChoose some **directories full of MP3**. Every directory is considered a **playlist** and processed separately from others. Inside every directory a file named ``mp3-player-settings.txt`` will be created containing the **settings for that directory** (for example the song to start with the next time that directory is played). These setting, if existing, will be **overwritten by manually provided parameters**. The directories I choose are \"C:/path/to/songs/\" and \"./Music/\".  \n\nThen there are two ways to provide the script with those directories: using a **file** or using **command line arguments** (all parameters between **\\[square brackets\\]** are to be considered optional):\n\n## Saving directories in file\nIn the directory the script is executed in create a file named ``mp3-player-directories.txt``. In that file you can insert the **directories to be played** this way:\n\n\tDIRECTORY [SORT_ORDER] [START_SONG]\n\tDIRECTORY [SORT_ORDER] [START_SONG]\n\t...\n\nHere \"DIRECTORY\" represents the directory in which to **look for songs**; \"SORT_ORDER\" is **optional**, must be a **sorting code** (see [Sorting](#sorting)), represents the **sort order** and defaults to track number order; \"START_SONG\" is **optional**, must be an **integer** (negative integers mean \"count from the right\"), represents the index of the **song to start with** and defaults to ``0``. **Save the file and run** the script. In this case the file could be:\n\n\tC:/path/to/songs/ random\n\t./Music/ modified-artist 15\n\n\n## Passing directories as command line arguments\n**Open a terminal** and navigate to the \"DIRECTORY\" the python script is in (run ``cd DIRECTORY``). Then run ``python3 FILENAME ARGUMENTS`` (*) replacing \"FILENAME\" with the name of the script. \"ARGUMENTS\" is the list of **directories to be played** and must be formatted this way:\n\n\tDIRECTORY [SORT_ORDER] [START_SONG] - ... - DIRECTORY [SORT_ORDER] [START_SONG]\n\nHere \"DIRECTORY\" represents the directory in which to **look for songs**; \"SORT_ORDER\" is **optional**, must be a **sorting code** (see [Sorting](#sorting)), represents the **sort order** and defaults to track number order; \"START_SONG\" is **optional**, must be an **integer** (a negative integer means \"count from the right\"), represents the index of the **song to start with** and defaults to ``0``. For example (command line commands):\n\n\t\u003e cd C:/mp3-player/\n\t\u003e python3 mp3-player.py C:/path/to/songs/ random - ./Music/ modified-artist 15\n\n(*) Note that the command used for Python is **not always** ``python3``: it could be ``py``, ``python``, ``python3.6`` or others too.\n\n## Result\nThe music should start playing! Now you can use keys to navigate through songs and playlist, see [Keyboard controls](#keyboard-controls).\n# Dependencies\n* Requires either **[Python 3.6.x](https://www.python.org/downloads/)** or **[Python 3.7.x](https://www.python.org/downloads/)** (I didn't test older versions, but newer ones may work).\n* Install dependencies from [requirements.txt](requirements.txt) using this command: `python3 -m pip install -r requirements.txt`  \nIt will install the following [`pip`](https://packaging.python.org/tutorials/installing-packages/) **modules**: [python-vlc](https://pypi.org/project/python-vlc/); [mutagen](https://pypi.org/project/mutagen/).\n# Notes\n* When using random sort order the order of songs is **different every time** the script is executed.\n* Start song argument is **useless** when the sort order is random, so it's **not saved** in ``mp3-player-settings.txt``.\n* When out-of-range indices are provided as \"START_SONG\" they will be **normalized** using modulus.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstypox%2Fmp3-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstypox%2Fmp3-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstypox%2Fmp3-player/lists"}