Need help with AppleMusicUltra?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

205 Stars 8 Forks 156 Commits 8 Opened issues


Music Client for macOS. Upgrade your music experience with themes, styles, custom scripting and more. Uses WebKit and JavaScript.

Services available


Need anything else?

Contributors list

No Data

Ultra for Apple Music

This project uses the TypeSwift framework, a bridging-interface for TypeScript and Swift.

Download Latest Beta: Ultra (Preview 2) JUNE 26, 2021

Ultra for Music

The ultimate Music client with a customizable personality. Upgrade your music experience with themes, styles, custom scripting, personalized settings, friends, followers and more. Built on macOS Monterey with backwards compatibility in-mind.

Coming Soon v2

Brace yourselves, a major update is coming to Ultra! I've completely redesigned the codebase, added further functionality and freedom with custom scripting, as well as UI customization. Furthermore, I'm in the process of implementing a Spotify-like social feed that'll allow you to keep up with what your Music friends are listening to.

The current project, along with this README, need a complete rework. Since many of you have been waiting patiently – over the past year and a little bit – for the next release, I will be priortizing the publication of the standalone Ultra v2 app. The programmatic documentation will follow soon after.

In the meantime, feel free to checkout Music Friends. Any contribution is welcome and greatly appreciated!

Download Latest Stable Build (macOS 10.12 and higher) (25MB) Public Beta 1
(April 17, 2020)

Drag & drop to

if you want to keep it after trying. 🤗

Updating from an older version? Drag and drop to

and click


Personalize your music experience with the Customizer. User-selectable images, videos, web content and more.

Apple Music Ultra

Ultra for Music is a highly-customizable client. This project started as more of a POC for two-way communicable scripting through WebKit using both JavaScript and native Swift. Since then, it has become a fun little side-project.

Apple Music Ultra

Personalizing the experience was a major inspiration for Ultra. When I first approach a project (with a UI), the presentation and appearance is a major priority for me. Especially with an app such as Music – that is heavily used with a high retention rate – the lack of customization was enough for me to start anew.

Music 2 BETA

Start using the new Music without having to install the macOS 11 Big Sur beta.

Apple Music Ultra

Ultra is set to the AMWP beta by default. You can change this in

Configuration > MusicPlayer > Music.swift
static let url = Service.appleBeta.url     // Latest Beta Release
static let url =         // Latest Public Release


in the
enum at the bottom of Music.swift for more details.

The Customizer

The Customizer allows you to browse and apply themes using images, video and/or web animation. It also allows you to apply styles – which essentially manages the transparency, vibrancy and blurring effects for both

modes (using

Apple Music Ultra

Note: Since its last major update in June 2020, I have decided to transition Ultra away from

presentation through individual, native objects such as
. Instead, I have decided to transition towards one, universal object that is capable of presenting all

If I find that the

requires a considerable amount of power – or anything that impacts performance/energy – I will provide these native objects as an alternative method of presentation in the future. I have yet to compare the impacts of either. Please feel free to do so yourself and present your results as an issue.

Customizer: Themes

Liven up your music experience with the Ultra Visualizer BETA. Test these new dynamic themes by going to the main menu and selecting

Customize → Themes → Visualizer

Ultra Visualizer The Dynamic Gradient

created with HTML5/CSS3 animations and presented through


  • name:
    literal of the theme name
  • type:
    object to display in the
  • raw:
    literal of the content source (dependent on
  • style:
    object that sets the window appearance
  • isTransparent:
    that handles

Note that

is just another attribute of
. This is so that
can be easily packaged for saving, as well as being extracted as a single object.


  • .image
    : A still image that is preferably colourful and low resolution/quality
  • .video
    : A WebKit-friendly video that is streamable from a raw URL (
  • .webContent
    : Custom web pages that are used to present HTML5/CSS3 animations
  • .custom
    : User-selected media file (local or URL) to be displayed using

Dynamic Themes: Visualizer BETA

Since both

types have the same resulting effect to the end-user, they are being grouped as Dynamic Themes. You may see me using the terms interchangeably. Furthermore, due to the iTunes visualizer being discontinued, I thought it only appropriate to market dynamic themes under the term: Visualizer. You may also see me using this word interchangeably.

TL;DR: visualizer == dynamic == (.video || .webContent)

These dynamic themes use a combination of HTML5/CSS3 animations, as well as highly compressed video (preferably H.265 in an HEVC container). The resulting animations are presented beneath the standard blurring and vibrancy effects of

blurView: NSVisualEffectsView
. Thus, due to the finite detail required from these resources, it is recommended that you follow these standards:


  • Low quality, low resolution and high compression
  • Bright, vibrant colours
  • Short in length (
    < 20s
  • Loop-ready if possible

Since everything in

has a blurry, somewhat-dence overlay effect (
) – efficiency, performance and limiting resource demand is key. You do not need a fully-detailed, 1080p video with mediocre compression to act as a dynamic effect. Your videos should only provide what is necessary to get the desired effect.


Take my dynamic video theme, Kaleidoscope, as an example. You can find the raw video file that is streamed to Ultra here.
is a
video file that is about
long, with dimensions
. Furthermore, I edited the video to loop perfectly (although, due to the density of
, perfection is not required).


Head on over to

Themes > ThemeHTML.swift
. As you can see with
videoHTML(_ :)
, the HTML needed to play a video in
is 1 line of code.
static func videoHTML(_ urlString: String) -> String {
  let html = ""
  return html

You don't need to have WebDev experience to understand what this line of code does. It simply takes the most minimal approach of playing a fullscreen video, within a

, using the WebKit standards. The
attributes allow for the video to start playing automatically and at the custom
set (
100% = max
). The
will ensure that the following rule is met in most scenerios:
window.height <= window.length
(the window will never be taller than it is wider). Thus, it only makes sense to set the maximum height and leave width to


attribute allows the video to seamlessly autoplay in exactly that: a loop. If you want the dynamic theme to feel fluent and continuous - and not like a seconds-long clip on repeat - the video needs to have somewhat of a looping feel. If you have a short, small video file that you'd like to use as a dynamic theme, there are ways of creating a looping-effect without any real AV work. Online services like will essentially take your video, double its length, and put the second half of said video in reverse. This will create an effect similar to the GIF you see in the Music 2 section above.

Funnily enough, the Kaleidoscope video was originally an HTML5/CSS3 animation that demanded too many resources when run in the background

. So instead, I opened up QuickTime Player, started a screen recording and used the built-in Trim function to end the video somewhere close to how it looked at the start.

Voila! You've created a looping animation in about 2 minutes.


  • Low resource demand
  • Vibrant and colourful


type is exactly that: web content. I found that simple CSS3 animations demanded far less resources than a
type would. However, upon exploring more complex animations, it slowed the client down considerably. With these complex animations running in
, my Mac would start to heat up and the lag of simply scrolling through AMWP was unbearable. After all, the top-layer
is essentially presenting a transparent render of AMWP. Adding in another graphically-demanding visual will bring the client to a hault.

The Kaleidoscope theme vs. Gradient theme is a perfect example of choosing efficiency. When the Kaleidoscope CSS3 animation caused the client to lag, I simply recorded it as a local file in Safari. With some minor modifications, the animation was running smoothly as a

. It's all about finding the right balance.

I do plan on testing for the most efficient method of presentation – taking performance, battery life and efficiency into account.


The Dynamic Gradient theme is a lot more straight-forward. This file is so small that I was able to include it, locally, within the project. It took three lines of CSS to accomplish (Technically one line, but who's counting? The compiler? Oh):

.css-gradient { background: linear-gradient(270deg, #ee7752, #e73c7e, #6314e6, #0960f2, #23d5ab); background-size: 1000% 1000%; -webkit-animation: Gradient 40s ease infinite; animation: Gradient 40s ease infinite; }
@-webkit-keyframes Gradient { 0%{background-position:0% 50%} 50%{background-position:100% 50%} 100%{background-position:0% 50%} }
@keyframes Gradient { 0%{background-position:0% 50%} 50%{background-position:100% 50%} 100%{background-position:0% 50%} }

More Visualizer effects are on the way!

Customizer: Styles

Apple Music Ultra

There are currently 7 styles to choose from, each with its own



           Material              Appearance       Intensity
preset:    .appearanceBased      .system            70%
frosty:    .sheet                .light             80%
bright:    .mediumLight          .light             50%
energy:    .light                .light             30%
cloudy:    .ultraDark            .dark              80%
shadow:    .toolTip              .dark              50%
vibing:    .dark                 .dark              30%

Styles are the top-layer effects that overlay the

, as well as determine
appearance modes. Using
, they can be set to overlap your object-based theme to add some vibrant effects; or alternatively, they can be set to blur your system background using
Theme.isTransparent = true

Custom Themes Temporarily Disabled

Apple Music Ultra Setting a custom, user-selected image is as simple as prompting the user for the

path of their
and setting it as the
let imageURL = selectImageFile()
setTheme(NSVisualEffectView.Material, darkMode: Bool, media: imageURL, type: "image")
func selectImageFile() -> URL {
    let dialog = NSOpenPanel()
    dialog.allowsMultipleSelection = false
    dialog.allowedFileTypes = ["png", "jpg", "jpeg"]

if (dialog.runModal() == NSApplication.ModalResponse.OK) {
    if let result = dialog.url?.absoluteURL { return result }



Appearance modes are now an attribute of

Style.get().isDark      // Returns the active Style appearance mode      // Returns the active Theme appearance mode

Just wanted to give a shout out to the devs behind the Web Player for designing this beautiful web app. The design of the UI seems to conform to its containers'

. Meaning everything in the web app has a Light mode and Dark mode property and conforms to whatever the
object is set to.

Thus, this property's main function is to toggle the Light/Dark mode of AMWP, as well as the entire application as a whole.

ViewController Overview back to front

  • FXWebView:
    that displays all
    content using local HTML (specific to
    • if Theme.isTransparent { fxWebView.isHidden = true }
  • BlurView:
    that presents the window
  • WebView:
    presents and interacts with AMWP through JavaScript
  • CustomizerView:
    embedded NSView
    that presents CustomizerViewController
    • CustomizerViewController utilizes the WKScriptMessageHandler protocol for communicating global
      updates upon selection


TODO: Write this out.

JavaScript Injection

TODO: Write this out.


  • alpha: The original Ultra for Apple Music build
    • Prior to restructuring the Themes & Style code and adding the new Customizer from private repository
  • legacy: Ultra for Apple Music with support for macOS 10.13 and below
  • webkit/fx: All effects (static and dynamic) done through a single WebKit manager
  • ~~beta:~~ (retired) The nightly builds for the current master that will replace the alpha build as master
  • ~~lite/musish:~~ (retired) Ultra LITE for Musish (GitHub)

Note: The master branch has recently been replaced with newer code for better integration with Big Sur. The previous code (August 2020) is still available and has been moved to the

branch. The previous code was mashed together and added-to when my free time was available. In short, it's a mess.

I am still in the process of rewriting and restructuring the new code as I learn better, more efficient ways of doing things. I will do my best to update the README and documentation as progress is made. Again, this is just a side-project. I will only be adding to it when I have free time available. If I want to implement a fun new feature that I think users will enjoy, I will prioritize that over cleaning and restructuring – as this is a side-project. Thank you for your patience!


Requires macOS 10.12 or later.

Please note that the app is being built with Swift 5.2

This app is currently under heavy development. Expect major structural changes.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.