Add Master and Return Track Support

[jwhector]

Add Master and Return Track Support

This PR adds support for accessing master and return tracks throughout the AbletonOSC API, independent of the number of tracks in the set. Previously, only regular Audio/MIDI tracks could be accessed via the Track, Device, and Song APIs. Now, master and return tracks can be accessed using string identifiers or are automatically included when enumerating "all" tracks.

This PR closes #47 and reimplements #84. Referencing that discussion, a goal with this PR was to keep a similar namespace to what's already implemented by the API for maximum legibility and backward compatibility, as well as to enable querying master and send/return tracks independent of the number of tracks in the set. More details about the specific implementation below.

Motivation

• Master and return tracks are essential parts of any Ableton Live set, but were previously inaccessible via the OSC API
• Users can now query device parameters, meters, and other properties on master and return tracks
• Bulk operations (wildcards, song data exports) now include all track types

Changes

1. Added Shared Track Resolution Helper

File: abletonosc/handler.py

Created a reusable _resolve_track() method on AbletonOSCHandler that resolves track parameters to track objects:

• Numeric index (e.g., 0, 1, 2) → regular tracks via self.song.tracks[index]
• "master" or "main" (case-insensitive) → self.song.master_track
• Return track prefix (e.g., "A", "B") → matches against self.song.return_tracks names (format: "A-Reverb", "B-Delay")

2. Track API: Master and Return Track Support

File: abletonosc/track.py

Changes:

• Refactored track_callback to use the shared _resolve_track() helper
• Extended wildcard "*" to include master and return tracks

New Usage:

# Access master track
/live/track/get/output_meter_level master
/live/track/get/volume master
/live/track/set/volume master 0.75

# Access return tracks by prefix
/live/track/get/output_meter_level A
/live/track/get/volume B
/live/track/set/mute A 1

# Wildcard now includes master + returns
/live/track/get/name *
# Returns: track_0_name, track_1_name, ..., master_name, A-Reverb, B-Delay, ...

3. Device API: Master and Return Track Support

File: abletonosc/device.py

Changes:

• Refactored device_callback to use the shared _resolve_track() helper

New Usage:

# Access devices on master track
/live/device/get/name master 0
/live/device/get/parameter/value master 0 2

# Access devices on return tracks
/live/device/get/name A 0
/live/device/set/parameter/value B 1 2 0.5

4. Song API: Extended Enumeration Functions

File: abletonosc/song.py

4a. song_get_track_names

Extended to include master and return tracks when enumerating "all":

# No params: returns all track names including master + returns
/live/song/get/track_names

# With -1: returns range + master + returns
/live/song/get/track_names 0 -1

# Explicit range: regular tracks only (existing behavior)
/live/song/get/track_names 0 5

4b. song_get_track_data

Extended to process master and return tracks when track_index_max == -1:

# Includes master + returns
/live/song/get/track_data 0 -1 track.name track.volume

# Explicit range: regular tracks only
/live/song/get/track_data 0 5 track.name track.volume

Note: Handles tracks without clip_slots (master/returns don't have clips) gracefully.

4c. song_export_structure

Always includes master and return tracks in the exported JSON:

New JSON structure:

{
  "tracks": [
    // Regular tracks (existing)
  ],
  "master_track": {
    "name": "Master",
    "devices": [...]
  },
  "return_tracks": [
    {
      "index": 0,
      "name": "A-Reverb",
      "devices": [...]
    },
    {
      "index": 1,
      "name": "B-Delay",
      "devices": [...]
    }
  ]
}

Technical Details

Response Format

When using string identifiers, OSC responses include the string identifier:

• /live/track/get/volume master → ("master", 0.75)
• /live/track/get/volume A → ("A", 0.8)
• /live/device/get/name master 0 → ("master", 0, "Compressor")

This maintains consistency with the existing API where numeric indices are returned.

Backward Compatibility

All changes are fully backward compatible:

• Existing numeric index usage works exactly as before
• Wildcard behavior is extended but maintains the same response format
• Explicit numeric ranges in song functions work unchanged

Tests

tests/test_track.py

New tests verify that track properties (name, volume, panning, mute, num_devices) can be read and written using the string identifiers "master" / "main" for the master track and a return track prefix (e.g. "A") for return tracks. A listener test confirms start_listen / stop_listen work correctly with the "master" identifier. Additional tests assert that an unrecognised string identifier returns None without crashing, and that pre-existing numeric integer indexing continues to work as before.

tests/test_song.py

New tests cover the two modified endpoints:

• /live/song/get/track_names — verifies that a no-argument call (or a range ending in -1) includes the master and return tracks in the response, while an explicit numeric range excludes them.
• /live/song/get/track_data — verifies that a range ending in -1 includes master/return track data, that an explicit range does not, and that querying clip, clip_slot, or device properties over a range that includes master/return tracks (which have no clip_slots) does not raise an error.

Checklist

• The title is descriptive and summarises the new changes
• The code and any comments are consistent with the current code style
• For any new or modified API endpoints, I have added appropriate documentation to README.md
• For any new or modified API endpoints, I have added unit tests covering the new functionality
• I have verified that all unit tests pass (see CONTRIBUTING.md for guidance)

[CLAassistant]

All committers have signed the CLA.

[thevictormaina]

masterful work. would love to see this merged.