macotron.player

Play an internet radio stream or a podcast episode in Macotron itself. The player shows in Control Center, answers the media keys, and keeps playing when you reload a plugin.

// Play SomaFM Groove Salad and show the song in the menu bar.
macotron.player.play("https://ice1.somafm.com/groovesalad-128-mp3", { title: "Groove Salad" });

function paint(s) {
  s = s || macotron.player.state();
  macotron.menubar.status("radio", {
    title: s.status === "stopped" ? "" : (s.streamTitle || s.title || ""),
    sfSymbol: "radio",
    onClick: () => macotron.player.toggle(),
  });
}
paint();
macotron.on("player:changed", paint);

Playing

play(url, { title?, artist?, artwork?, position? }): boolean

Stops whatever is playing and starts url. Only http, https, and file URLs play; for any other scheme the call returns false and nothing changes.

title and artist show in state() and in Control Center.
artwork is an image URL or file path for Control Center.
position is the second to start at, for resuming a podcast.

The call returns at once. The stream loads in the background: watch player:changed for "playing" or "error".

pause(): void

Pauses playback.

resume(): void

Continues after a pause.

toggle(): void

Pauses when playing, resumes when paused.

stop(): void

Stops and forgets the item. state() is then "stopped".

seek(seconds): void

Jumps to an absolute position. Live streams have no duration and ignore it.

setVolume(volume): void

Sets the player's volume from 0 to 1. This is the player's own volume, not the system volume; use macotron.audio for that.

Reading

state(): { status, url, title, artist, streamTitle, position, duration, volume, error? }

status is one of:

"stopped": nothing loaded. url, title, and the other strings are null.
"loading": connecting or buffering.
"playing"
"paused"
"error": the stream did not load or dropped. error has AVFoundation's message. Macotron does not retry; call play() again.

streamTitle is the song a radio station sends in its ICY metadata, usually Artist - Song, or null. position and duration are seconds. duration is null for a live stream.

Events

player:changed

Fires with state() when the status, the item, streamTitle, or error changes. It does not fire as the position moves: a plugin that shows progress reads state() on its own timer.

Lifetime and the system

There is one player for all of Macotron. Reloading a plugin does not stop it, so a reloaded plugin reads state() to catch up. Quitting Macotron stops it.

The player publishes to the system Now Playing, so Control Center, the media keys, and macotron.media see Macotron like any other player. Play, pause, and play/pause work there, and skip back and forward 30 seconds when the item has a duration.

AVPlayer plays MP3, AAC, and HLS streams. Some stations send Ogg Vorbis or Opus, which fail with "error".