{"id":18293518,"url":"https://github.com/mcthomas/apple-music-cli-player","last_synced_at":"2025-10-14T13:06:11.763Z","repository":{"id":63387106,"uuid":"488052816","full_name":"mcthomas/Apple-Music-CLI-Player","owner":"mcthomas","description":"A simple command-line Apple Music controller script which includes a \"Now Playing\" widget function, a playback function, and a list-out function for your Mac's Music.app library, written in sh.","archived":false,"fork":false,"pushed_at":"2023-03-23T07:30:31.000Z","size":2809,"stargazers_count":155,"open_issues_count":2,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-14T13:04:44.211Z","etag":null,"topics":["apple","applescript","automation","bash","cli","command-line","command-line-tool","console","macos","music","osascript","osx","script","sh","shell","terminal","tui","unix","widget","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/mcthomas.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,"zenodo":null}},"created_at":"2022-05-03T02:18:53.000Z","updated_at":"2025-10-12T21:09:43.000Z","dependencies_parsed_at":"2025-07-30T04:26:21.195Z","dependency_job_id":"b2fb196d-66ed-4996-bea9-f4f8fdaccb54","html_url":"https://github.com/mcthomas/Apple-Music-CLI-Player","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mcthomas/Apple-Music-CLI-Player","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcthomas%2FApple-Music-CLI-Player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcthomas%2FApple-Music-CLI-Player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcthomas%2FApple-Music-CLI-Player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcthomas%2FApple-Music-CLI-Player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcthomas","download_url":"https://codeload.github.com/mcthomas/Apple-Music-CLI-Player/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcthomas%2FApple-Music-CLI-Player/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018696,"owners_count":26086604,"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","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["apple","applescript","automation","bash","cli","command-line","command-line-tool","console","macos","music","osascript","osx","script","sh","shell","terminal","tui","unix","widget","zsh"],"created_at":"2024-11-05T14:24:53.486Z","updated_at":"2025-10-14T13:06:11.727Z","avatar_url":"https://github.com/mcthomas.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apple Music CLI Player\n\n*Tested on macOS 12 \u0026 13 (likely to work on macOS 10.15, 11). **Can be called with the system default zsh.** I recommend aliasing am.sh to `alias am=zsh path/to/am.sh`, or moving its three individual functions into your .zshrc.*\n\n**Goal:** Provide a simple command-line interface to listing out, playing songs from, and utilizing controls for Music.app.  I decided against using a library such as ncurses to build a full TUI application, as I think it is preferable to interface via quick commands and a light \"widget\".\n\n\u003cimg src=\"np.png\" width=\"800\"/\u003e\n\n## Now Playing (np)\n\nEnjoy a simple \"Now Playing\" widget from your terminal.  Uses standard Unix tooling/piping, AppleScript for interfacing with Apple Music, and [Viu](https://github.com/atanunq/viu) for displaying the album art images.  It also includes keyboard shortcut bindings for basic playback controls.  Apart from toggling shuffle, toggling repeat, and changing the Music.app-specific volume, the other controls are already accessible from the special Fn key functions/touch bar.  \n\nDependencies: [Viu](https://github.com/atanunq/viu) (unless you always use text mode)\n\nConfiguration: \n\n* Place album-art.applescript at ~/Library/Scripts/album-art.applescript, or configure a valid path in the np() func of am.sh for wherever you decide to keep it\n* (Optional) In the np() func of am.sh, adjust the `-h` dimension of the album art (look for the two calls to `viu`) to ensure a square appearance with your terminal emulator's line spacing\n\nUsage (aliased): `am np`\n\nUsage (not aliased): `zsh am.sh np`\n```\nnp                    Open the \"Now Playing\" TUI widget.\n                      (Music.app track must be actively\n\t\t      playing or paused)\nnp -t\t\t      Open in text mode (disables album art)\n\nnp keybindings:\n\np                     Play / Pause\nf                     Forward one track\nb                     Backward one track\n\u003e                     Begin fast forwarding current track\n\u003c                     Begin rewinding current track\nR                     Resume normal playback\n+                     Increase Music.app volume 5%\n-                     Decrease Music.app volume 5%\ns                     Toggle shuffle\nr                     Toggle song repeat\nq                     Quit np\nQ                     Quit np and Music.app\n?                     Show / hide keybindings\n```\n\nNotes: \n* Attempting to play the previous track with an empty queue will kill the script\n* album-art.applescript is a modified version of [this script,](https://dougscripts.com/itunes/2014/10/save-current-tracks-artwork/) written by AppleScript wizard [Doug Adams](https://dougscripts.com/itunes/faq_cont.php)♡\n\n## List\n\nList out all song groupings of a specific type or all songs of a specific song grouping in your library.  The song grouping type is dictated by the flag you pass. By calling list without specifying a title after the flag, you will see a printout of all the titles of that flag's collection type. \n\nUsage (aliased): `am list [-grouping] [name]`\n\nUsage (not aliased): `zsh am.sh list [-grouping] [name]`\n```\nlist -s               List all songs in your library.\nlist -r               List all records.\nlist -r PATTERN       List all songs in the record PATTERN.\nlist -a               List all artists.\nlist -a PATTERN       List all songs by the artist PATTERN.\nlist -p               List all playlists.\nlist -p PATTERN       List all songs in the playlist PATTERN.\nlist -g               List all genres.\nlist -g PATTERN       List all songs in the genre PATTERN.\n```\nExample: `am list -r In Rainbows` (not case-sensitive)\n\nNotes: \n* Music.app does not need to be open or closed; it should launch itself silently when `list` is called\n* Only works on tracks saved to your Library (but they do not need to be downloaded)\n* Remember to escape any special characters or punctuation if passing a title (or wrap it in double quotes)\n\n## Play\n\nBegin playback of different song groupings or a specific song grouping in your library. The song grouping type is dictated by the flag you pass.  By calling play without specifying a title after the flag, you are prompted to select a title of that flag's collection type on the fly via [fzf](https://github.com/junegunn/fzf). Unfortunately there is no simple way to play, for example, a specific album or songs from a specific artist with AppleScript, but I was able to modify code shared by a \"jccc\" [here](https://discussions.apple.com/thread/1053355), as a workaround which involves automatically creating a single temporary playlist in your library that is utilized by play().\n\nDependencies: [fzf](https://github.com/junegunn/fzf) (unless you always play groupings by name)\n\nUsage (aliased): `am play [-grouping] [name]`\n\nUsage (not aliased): `zsh am.sh play [-grouping] [name]`\n```\nplay -s               Fzf for a song and begin playback.\nplay -s PATTERN       Play the song PATTERN.\nplay -r               Fzf for a record and begin playback.\nplay -r PATTERN       Play from the record PATTERN.\nplay -a               Fzf for an artist and begin playback.\nplay -a PATTERN       Play from the artist PATTERN.\nplay -p               Fzf for a playlist and begin playback.\nplay -p PATTERN       Play from the playlist PATTERN.\nplay -g               Fzf for a genre and begin playback.\nplay -g PATTERN       Play from the genre PATTERN.\nplay -l               Play from your entire library.\n```\nExample: `am play -a Radiohead` (not case-sensitive)\n\nNotes: \n* Music.app does not need to be open or closed; it should launch itself silently when `play` is called\n* Only works on tracks saved to your Library (but they do not need to be downloaded)\n* Remember to escape any special characters or punctuation if passing a title (or wrap it in double quotes)\n* calling `-p Library` will result in quite a delay, unlike `-l`, because it requires copying all the songs in your library into the temporary playlist\n\n### Optional AirPlay Snippet (not in src)\n\nToggle the Music.app AirPlay audio output for a specific device. \n\nConfiguration: \n* Adjust the device strings to a device hostname of your choosing\n* Ideally adapt the argument name to match\n\n```\nif [ $1 = \"atv\" ]\n   then\n    isActive=$(osascript -e 'tell application \"Music\" to get selected of AirPlay device \"Apple TV\"')\n    if [ $isActive = 'false' ]\n    then\n      osascript -e 'tell application \"Music\" to set selected of AirPlay device \"Apple TV\" to true'\n    else\n      osascript -e 'tell application \"Music\" to set selected of AirPlay device \"Apple TV\" to false'\n  fi\nfi\n```\nExample: `zsh ap.sh atv`\n\n### Known Problems\n\n- Error: `execution error: Music got an error: Application isn’t running. (-600)`\n  - Solution: Reboot. It seems to occur occasionally after having had Music.app open for too long while your Mac has slept. Other potential solutions can be found [here](https://stackoverflow.com/questions/19957268/applescript-fails-with-error-600-when-launched-over-ssh-on-mavericks)\n- Blinking for each output refresh when running np()\n  - Consider using a lighter-weight terminal emulator, or even Terminal.app, where this doesn't seem to occur. I am not sure how to mitigate this for heavier terminal emulators such as iTerm2\n\n### Ideas For Improvement\n\n* am.sh could be expanded with a function to call new AppleScript snippets to create, delete, or refine playlists; it would also be nice to be able to queue (as apposed to immediately play) a song or a group of songs, which is possible (though there is no native corresponding AppleScript function to accomplish this at present)\n* This project could be forked and used in the backend to create a full client alternative to Music.app, though it would not be possible to browse for and save tracks outside of the user's library\n* See the Script Editor.app's dictionary API (Music.sdef) for an exhaustive reference of all the native Music.app variables and functions that can be interfaced via AppleScript\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcthomas%2Fapple-music-cli-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcthomas%2Fapple-music-cli-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcthomas%2Fapple-music-cli-player/lists"}