Automate everything

Getting Started

Scripts are plain .js files placed in your scripts folder:

~/Library/Application Support/OrangeMusicPlayer/Scripts/

Open the folder from the menu bar: Scripts → Open Scripts Folder. Orange detects new and changed scripts automatically — no restart needed.

To run an on-demand script, use the Scripts menu or the Scripts panel in the sidebar. Event-driven scripts run automatically when their trigger fires.

Script Metadata

Add a comment block at the top of your script to declare metadata:

// @name       My Script
// @description What it does
// @author     Your Name
// @event      trackChanged

Console

Use console.log(), console.warn(), and console.error() to send output to the Script Console. Open it with Scripts → Script Console or Cmd+Shift+J.

console.log('Hello', 'world');    // supports multiple arguments
console.warn('Heads up!');
console.error('Something broke');

orange.player

Control playback and read the current player state.

Methods

Properties

var track = orange.player.currentTrack;
if (track) {
    console.log(track.title + ' by ' + track.artist);
    console.log('Position: ' + orange.player.position + 's');
}

// Set volume to 80%
orange.player.volume = 0.8;

orange.library

Search and retrieve tracks, albums, and artists from your library.

orange.playlists

Create, delete, and manage playlists.

orange.effects

Inspect and control the audio effects chain (EQ, reverb, AU plugins).

var slots = orange.effects.chain();
for (var i = 0; i < slots.length; i++) {
    if (slots[i]) {
        console.log(slots[i].name + ' — bypassed: ' + slots[i].isBypassed);
    }
}

// Bypass the first effect
orange.effects.bypass(0, true);

// Load factory preset #0 on slot 1
orange.effects.loadPreset(1, 0, 'factory');

Events

Register callbacks for playback and library events using orange.on().

orange.on('trackChanged', function(track) {
    console.log('Now playing: ' + track.title);
});

orange.on('playbackPaused', function() {
    console.log('Paused');
});

To bind an event-driven script, add @event in the metadata header. The script will automatically run when that event fires, and your orange.on() handlers will be called.

Track Object

Track objects returned by the API have these properties:

Album objects have: id, title, artist, year, trackCount.
Artist objects have: id, name, albumCount, trackCount.
Playlist objects have: id, name, trackCount.

Examples

// @name       Quick Favorites Playlist
// @description Collects all favorited tracks into a new playlist
// @author     Orange Music Player

var allTracks = orange.library.searchTracks('');
var favorites = [];

for (var i = 0; i < allTracks.length; i++) {
    if (allTracks[i].isFavorite) {
        favorites.push(allTracks[i]);
    }
}

console.log('Found ' + favorites.length + ' favorite tracks');

if (favorites.length > 0) {
    orange.playlists.create('My Favorites (Script)');

    // Find the newly created playlist
    var playlists = orange.playlists.list();
    var target = null;
    for (var j = 0; j < playlists.length; j++) {
        if (playlists[j].name === 'My Favorites (Script)') {
            target = playlists[j];
        }
    }

    if (target) {
        for (var k = 0; k < favorites.length; k++) {
            orange.playlists.addTrack(target.id, favorites[k].id);
        }
        console.log('Added ' + favorites.length + ' tracks to playlist');
    }
}

// @name       Genre Logger
// @description Logs genre info every time the track changes
// @author     Orange Music Player
// @event      trackChanged

orange.on('trackChanged', function(track) {
    if (!track) return;

    var genre = track.genre || 'Unknown';
    console.log(track.title + ' [' + genre + '] by ' + (track.artist || 'Unknown'));

    // Detect jazz and log something fun
    if (genre.toLowerCase().indexOf('jazz') !== -1) {
        console.log('Jazz detected! Smooth listening ahead.');
    }
});

// @name       Top 20 Most Played
// @description Creates a playlist from your 20 most-played tracks
// @author     Orange Music Player

var all = orange.library.searchTracks('');

// Sort by play count descending
all.sort(function(a, b) { return b.playCount - a.playCount; });

var top = all.slice(0, 20);
console.log('Top track: ' + top[0].title + ' (' + top[0].playCount + ' plays)');

orange.playlists.create('Top 20 Most Played');

var playlists = orange.playlists.list();
var target = null;
for (var i = 0; i < playlists.length; i++) {
    if (playlists[i].name === 'Top 20 Most Played') {
        target = playlists[i];
    }
}

if (target) {
    for (var i = 0; i < top.length; i++) {
        orange.playlists.addTrack(target.id, top[i].id);
    }
    console.log('Created playlist with ' + top.length + ' tracks');
}