{"id":21659410,"url":"https://github.com/GuardKenzie/miniplayer","last_synced_at":"2025-07-17T22:32:02.996Z","repository":{"id":38211166,"uuid":"334152946","full_name":"GuardKenzie/miniplayer","owner":"GuardKenzie","description":"A curses based mpd client with basic functionality and album art.","archived":false,"fork":false,"pushed_at":"2024-06-09T05:23:41.000Z","size":1738,"stargazers_count":122,"open_issues_count":3,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-06T06:36:28.280Z","etag":null,"topics":["album-art","lightweight","mpd-client","music","python"],"latest_commit_sha":null,"homepage":"","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/GuardKenzie.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-29T13:25:30.000Z","updated_at":"2025-03-18T16:45:51.000Z","dependencies_parsed_at":"2024-11-25T09:43:08.254Z","dependency_job_id":null,"html_url":"https://github.com/GuardKenzie/miniplayer","commit_stats":{"total_commits":138,"total_committers":8,"mean_commits":17.25,"dds":0.536231884057971,"last_synced_commit":"845ea545bd9df6e9d5f0f20fa75a64b4f0e2d624"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/GuardKenzie/miniplayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuardKenzie%2Fminiplayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuardKenzie%2Fminiplayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuardKenzie%2Fminiplayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuardKenzie%2Fminiplayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GuardKenzie","download_url":"https://codeload.github.com/GuardKenzie/miniplayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuardKenzie%2Fminiplayer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264947200,"owners_count":23687290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["album-art","lightweight","mpd-client","music","python"],"created_at":"2024-11-25T09:31:00.989Z","updated_at":"2025-07-17T22:32:02.638Z","avatar_url":"https://github.com/GuardKenzie.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Miniplayer\n\nA curses based mpd client with basic functionality and album art.\n\n![player-preview](https://github.com/GuardKenzie/miniplayer/blob/main/img/preview.png?raw=true)\n\nAfter installation, the player can be opened from the terminal with `miniplayer`.\n\n## Installation\n\nThis package can be installed by:\n1. Cloning this repository to your computer and running\n```\npython setup.py install\n```\n2. Through PyPi with\n```\npip install miniplayer\n```\n3. By installing the `miniplayer-git` package with your AUR package manager of choice.\n\n## Configuration\n\nThe config file is located at `~/.config/miniplayer/config`. The example configuration file, [`config.example`](config.example), has all the default values. You will need to create the file yourself.\n\n### player\nWow, that volume step is huge. Why isn't my album art centered?\n\n| Option         | Description                                                                                           |\n| -------------- | ----------------------------------------------------------------------------------------------------- |\n| font_width     | The width of your font in pixels in the actual terminal.                                              |\n| font_height    | The height of your font in pixels in the actual terminal.                                             |\n| volume_step    | The ammount (in percents) the volume will be adjusted on pressing the volume up and volume down keys. |\n| album_art_only | Whether or not to only draw the album art and no other track info (`true/false`).                     |\n| auto_close     | Whether or not to automatically close the player once the mpd playlist has concluded (`true/false`).  |\n| show_playlist  | Whether or not to show the playlist view.                                                             |\n\nThe `font_width` and `font_height` options are used to center the album art properly.Here is an example of how they should be measured.\n\n![font-example](https://github.com/GuardKenzie/miniplayer/blob/main/img/font.png?raw=true)\n\n\n### art\nWhy listen to music if you can't look at the pretty album art?\n\n| Option               | Description                                                                                   |\n| -------------------- | --------------------------------------------------------------------------------------------- |\n| image_method         | The method to use for drawing album art. Available values are `pixcat` and `ueberzug`.        |\n\n### mpd\nTell me your mpd address please!\n\n| Option | Description      |\n| ------ | ---------------- |\n| host   | The mpd host     |\n| port   | The mpd port     |\n| pass   | The mpd password |\n\n\n### keybindings\nThis section allows you to change the keybinds for the player. The format for a keybind is `key = action` (for example `p = play_pause` or `left = last_track`). \n\nTo use `shift` as a modifier, capitalize the keybinding (i.e. `shift + p` becomes `P` and `shift + left` becomes `Left`). **This only works for alpha keys and the arrow keys!**\n\n| Available actions |\n| ----------------- |\n| `play_pause`      |\n| `next_track`      |\n| `last_track`      |\n| `volume_down`     |\n| `volume_up`       |\n| `toggle_info`     |\n| `help`            |\n| `quit`            |\n| `select_down`     |\n| `select_up`       |\n| `select`          |\n| `move_up`         |\n| `move_down`       |\n| `shuffle`         |\n| `repeat`          |\n| `delete`          |\n| `command_line`   |\n\n\n### theme\nMake it yours!\n\n| Option       | Description                                                |\n| ------------ | ---------------------------------------------------------- |\n| accent_color | The color to use for selections in the playlist            |\n| bar_color    | The color for the progress bar                             |\n| time_color   | The color for the time stamp                               |\n| bar_body     | A single character to use for the body of the progress bar |\n| bar_head     | A single character to use for the head of the progress bar |\n| command_sep  | Characters used to seperate the command line               |\n| command_char | Characters to indicate the command line is open            |\n\nThe following terminal colors can be used:\n* `black`\n* `red`\n* `green`\n* `yellow`\n* `blue`\n* `magenta`\n* `cyan`\n* `white`\n\nYou can also use the magic colour called `auto`. If you pick it, the player will try to determine the dominant color in the album art and use that instead.\n\n\n## Default keybinds\n\n| Key          | Function                           |\n| ------------ | ---------------------------------- |\n| h            | Show keybinds                      |\n| p            | Play/pause                         |\n| \u003e            | Next track                         |\n| \u003c            | Last track                         |\n| q            | Quit                               |\n| +            | Volume up                          |\n| -            | Volume down                        |\n| i            | Toggle info                        |\n| Up           | Selection up                       |\n| Down         | Selection down                     |\n| Enter        | Play selected song                 |\n| Delete       | Remove selected song from playlist |\n| Shift + up   | Move selected song up              |\n| Shift + down | Move selected song down            |\n| x            | Shuffle playlist                   |\n| r            | Toggle repeat                      |\n| :            | Open command line                  |\n\nThese keybinds can be changed by editing the config file. See the [`config.example`](config.example) file for the format.\n    \n## The command line\n\nThe command line can be used to add songs to the current playlist. To launch it, press the `command_line` button (that's `:` by default). The command line supports some tab completion but you cannot move the caret left or right (yet).\n\nThe format is as follows:\n\n```\n[hierarchy] [tag1/tag2/tag3/...tagN]\n```\n\n![hierarchy](img/cmd.png)\n\n* You do not have to populate all the tags. if you type, for example, `artist Phoebe Bridgers/` and hit enter, all of Phoebe's music in your library will be added to the playlist.\n\n* **NOTE** You do not type the seperator! It is added automatically. Just use a space!\n\nThe hierarchy controls the order of the tags and what each tag represents. Currently there are 4 available hierarchies with plans to add user configurable ones in the future.\n\n### Hierarchies\n| Hierarchy | Tag format        |\n| --------- | ----------------- |\n| album     | album/song        |\n| artist    | artist/song       |\n| song      | song              |\n| aa        | artist/album/song |\n\n\n### Command line keys\n\n| Key    | Action                                          |\n|--------|-------------------------------------------------|\n| Escape | Exit command line                               |\n| Enter  | Attempt to add the current tags to the playlist |\n\n## F.A.Q.\n- **Q:** Album art is not showing up.  \n   **A:** Try changing `image_method` from `pixcat` to `ueberzug` or vice versa.\n\n- **Q:** Album art is too big/too small.  \n   **A:** You need to configure `font_height` and `font_width`. Their values should be the actual pixel height and width of a character in your terminal.\n\n\n## More screenshots!\n\n![playlist](img/playlist.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGuardKenzie%2Fminiplayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGuardKenzie%2Fminiplayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGuardKenzie%2Fminiplayer/lists"}