• Player Versions
• Quick Minimal Setup
• Full Options Reference
• Configuration
  • ui
  • presetNames
  • features
  • alignment
• Track Settings
  • trackGroup
  • Track Options
  • Audio Source Options
  • Track Alignment Options
• Visualizations
  • text
  • image
  • perTrackImage
  • waveform
  • midi
  • sheetMusic
  • warpingMatrix
• Keyboard and Loop Controls
• Things to Check

Player Versions

trackswitch.js ships one browser-ready JavaScript bundle for all player versions. The interactive sync player also needs the separate worker file.

Quick Minimal Setup

<script src="dist/js/trackswitch.js"></script>

<trackswitch-player>
  <script type="application/json">
    {
      "ui": [
        {
          "type": "trackGroup",
          "trackGroup": [
            {
              "title": "Track 1",
              "sources": [{ "src": "track1.mp3", "type": "audio/mpeg" }]
            }
          ]
        }
      ]
    }
  </script>
</trackswitch-player>

import { defineTrackswitchDefaultElement, type TrackSwitchInit } from 'trackswitch';

const config: TrackSwitchInit = {
  ui: [
    {
      type: 'trackGroup',
      trackGroup: [
        {
          title: 'Track 1',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
        },
      ],
    },
  ],
};

defineTrackswitchDefaultElement();
document.querySelector('trackswitch-player')!.config = config;

import { useMemo } from 'react';
import { TrackSwitchPlayer, type TrackSwitchInit } from 'trackswitch/react';

export function ExamplePlayer() {
  const config = useMemo<TrackSwitchInit>(() => {
    return {
      ui: [
        {
          type: 'trackGroup',
          trackGroup: [
            {
              title: 'Track 1',
              sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
            },
          ],
        },
      ],
    };
  }, []);

  return <TrackSwitchPlayer config={config} className="trackswitch-host" />;
}

<script setup lang="ts">
import { TrackSwitchPlayer, type TrackSwitchInit } from 'trackswitch/vue';

const config: TrackSwitchInit = {
  ui: [
    {
      type: 'trackGroup',
      trackGroup: [
        {
          title: 'Track 1',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
        },
      ],
    },
  ],
};
</script>

<template>
  <TrackSwitchPlayer :config="config" class="trackswitch-host" />
</template>

<script src="dist/js/trackswitch.js"></script>

<trackswitch-sync-player>
  <script type="application/json">
    {
      "ui": [
        {
          "type": "trackGroup",
          "trackGroup": [
            {
              "title": "Track 1",
              "sources": [{ "src": "track1.mp3", "type": "audio/mpeg" }],
              "alignment": { "column": "track_1_time" }
            },
            {
              "title": "Track 2",
              "sources": [{ "src": "track2.mp3", "type": "audio/mpeg" }],
              "alignment": { "column": "track_2_time" }
            }
          ]
        }
      ],
      "alignment": {
        "csv": "alignment.csv",
        "referenceTimeColumn": "track_1_time"
      }
    }
  </script>
</trackswitch-sync-player>

import { defineTrackSwitchSyncPlayerElement, type TrackSwitchInit } from 'trackswitch';

const config: TrackSwitchInit = {
  ui: [
    {
      type: 'trackGroup',
      trackGroup: [
        {
          title: 'Track 1',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_1_time' },
        },
        {
          title: 'Track 2',
          sources: [{ src: 'track2.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_2_time' },
        },
      ],
    },
  ],
  alignment: {
    csv: 'alignment.csv',
    referenceTimeColumn: 'track_1_time',
  },
};

defineTrackSwitchSyncPlayerElement();
document.querySelector('trackswitch-sync-player')!.config = config;

import { TrackSwitchSyncPlayer, type TrackSwitchInit } from 'trackswitch/react';

const config: TrackSwitchInit = {
  ui: [
    {
      type: 'trackGroup',
      trackGroup: [
        {
          title: 'Track 1',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_1_time' },
        },
        {
          title: 'Track 2',
          sources: [{ src: 'track2.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_2_time' },
        },
      ],
    },
  ],
  alignment: {
    csv: 'alignment.csv',
    referenceTimeColumn: 'track_1_time',
  },
};

export function ExamplePlayer() {
  return <TrackSwitchSyncPlayer config={config} className="trackswitch-host" />;
}

<script setup lang="ts">
import { TrackSwitchSyncPlayer, type TrackSwitchInit } from 'trackswitch/vue';

const config: TrackSwitchInit = {
  ui: [
    {
      type: 'trackGroup',
      trackGroup: [
        {
          title: 'Track 1',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_1_time' },
        },
        {
          title: 'Track 2',
          sources: [{ src: 'track2.mp3', type: 'audio/mpeg' }],
          alignment: { column: 'track_2_time' },
        },
      ],
    },
  ],
  alignment: {
    csv: 'alignment.csv',
    referenceTimeColumn: 'track_1_time',
  },
};
</script>

<template>
  <TrackSwitchSyncPlayer :config="config" class="trackswitch-host" />
</template>

<script src="dist/js/trackswitch.js"></script>

<trackswitch-sync-interactive>
  <script type="application/json">
    {
      "workerUrl": "dist/js/trackswitch-interactive-worker.js"
    }
  </script>
</trackswitch-sync-interactive>

import {
  defineTrackSwitchSyncInteractiveElement,
  type InteractiveTrackSwitchInit,
} from 'trackswitch/interactive';

const config: InteractiveTrackSwitchInit = {
  workerUrl: 'dist/js/trackswitch-interactive-worker.js',
};

defineTrackSwitchSyncInteractiveElement();
document.querySelector('trackswitch-sync-interactive')!.config = config;

import { TrackSwitchSyncInteractive } from 'trackswitch/react';
import type { InteractiveTrackSwitchInit } from 'trackswitch/interactive';

const config: InteractiveTrackSwitchInit = {
  workerUrl: 'dist/js/trackswitch-interactive-worker.js',
};

export function ExamplePlayer() {
  return <TrackSwitchSyncInteractive config={config} className="trackswitch-host" />;
}

<script setup lang="ts">
import { TrackSwitchSyncInteractive } from 'trackswitch/vue';
import type { InteractiveTrackSwitchInit } from 'trackswitch/interactive';

const config: InteractiveTrackSwitchInit = {
  workerUrl: 'dist/js/trackswitch-interactive-worker.js',
};
</script>

<template>
  <TrackSwitchSyncInteractive :config="config" class="trackswitch-host" />
</template>

Full Options Reference

TrackSwitch.createDefaultTrackSwitch(rootElement, {
  presetNames: ['Full Mix', 'Strings', 'Rhythm'],
  ui: [
    {
      type: 'image',
      src: 'cover.jpg',
      seekable: true,
      seekMarginLeft: 5,
      seekMarginRight: 5,
      style: 'margin: 0;',
    },
    {
      type: 'text',
      text: 'Choose which parts of the arrangement you want to hear.',
      bold: true,
      italic: false,
      fontSize: 18,
      align: 'center',
      style: 'margin: 0;',
    },
    {
      type: 'waveform',
      height: 160,
      waveformBarWidth: 2,
      maxZoom: 5,
      waveformSource: 'audible',
      playbackFollowMode: 'center',
      timer: false,
      seekMarginLeft: 3,
      seekMarginRight: 4,
      style: 'margin: 0;',
    },
    {
      type: 'trackGroup',
      rowHeight: 44,
      trackGroup: [
        {
          title: 'Violins',
          solo: true,
          volume: 0.9,
          pan: -0.2,
          image: 'violins.png',
          style: 'border-left: 3px solid #4f8dc9;',
          presets: [0, 1],
          sources: [
            { src: 'violins.mp3', type: 'audio/mpeg', startOffsetMs: 0, endOffsetMs: 0 },
            { src: 'violins.ogg', type: 'audio/ogg' },
          ],
        },
        {
          title: 'Drums',
          solo: false,
          volume: 1,
          pan: 0,
          image: 'drums.png',
          style: 'border-left: 3px solid #ed8c01;',
          presets: [0, 2],
          sources: [{ src: 'drums.mp3', type: 'audio/mpeg', startOffsetMs: -120, endOffsetMs: 250 }],
        },
      ],
    },
    {
      type: 'sheetMusic',
      src: 'score.musicxml',
      maxWidth: 960,
      maxHeight: 360,
      renderScale: 0.75,
      followPlayback: true,
      cursorColor: '#999999',
      cursorAlpha: 0.1,
      style: 'margin: 0;',
    },
  ],
  features: {
    exclusiveSolo: false,
    muteOtherPlayerInstances: true,
    globalVolume: true,
    trackVolumeControls: true,
    trackPanControls: true,
    repeat: false,
    tabView: false,
    iosAudioUnlock: true,
    keyboard: true,
    looping: true,
    seekBar: true,
    timer: true,
    presets: true,
    customizablePanelOrder: true,
  },
});

TrackSwitch.createTrackSwitchSyncPlayer(rootElement, {
  ui: [
    {
      type: 'image',
      src: 'score-overview.jpg',
      seekable: false,
      seekMarginLeft: 0,
      seekMarginRight: 0,
      style: 'margin: 0;',
    },
    {
      type: 'perTrackImage',
      seekable: true,
      seekMarginLeft: 4,
      seekMarginRight: 4,
      style: 'margin: 0;',
    },
    {
      type: 'text',
      text: 'Compare aligned tracks on the shared score timeline.',
      bold: true,
      fontSize: 18,
      align: 'center',
      style: 'margin: 0;',
    },
    {
      type: 'waveform',
      height: 160,
      waveformBarWidth: 3,
      maxZoom: 8,
      waveformSource: 0,
      playbackFollowMode: 'jump',
      timer: true,
      alignedPlayhead: true,
      showAlignmentPoints: true,
      seekMarginLeft: 3,
      seekMarginRight: 4,
      style: 'margin: 0;',
    },
    {
      type: 'trackGroup',
      rowHeight: 44,
      trackGroup: [
        {
          title: 'Track 1',
          solo: true,
          volume: 1,
          pan: 0,
          image: 'track1.png',
          style: 'border-left: 3px solid #4f8dc9;',
          sources: [{ src: 'track1.mp3', type: 'audio/mpeg', startOffsetMs: 0, endOffsetMs: 0 }],
          alignment: {
            column: 'track_1_time',
            synchronizedSources: [
              { src: 'track1-synced.mp3', type: 'audio/mpeg', startOffsetMs: 0, endOffsetMs: 0 },
            ],
          },
        },
        {
          title: 'Track 2',
          solo: false,
          volume: 0.92,
          pan: 0.1,
          image: 'track2.png',
          style: 'border-left: 3px solid #6c757d;',
          sources: [{ src: 'track2.mp3', type: 'audio/mpeg', startOffsetMs: 50, endOffsetMs: 0 }],
          alignment: {
            column: 'track_2_time',
            synchronizedSources: [{ src: 'track2-synced.mp3', type: 'audio/mpeg' }],
          },
        },
      ],
    },
    {
      type: 'sheetMusic',
      src: 'score.musicxml',
      measureColumn: 'measure',
      maxWidth: 960,
      maxHeight: 360,
      renderScale: 0.75,
      followPlayback: true,
      cursorColor: '#999999',
      cursorAlpha: 0.1,
      style: 'margin: 0;',
    },
    {
      type: 'warpingMatrix',
      height: 240,
      tempoSmoothingSeconds: 5,
      bpm: 'infer_score',
      style: 'margin: 0;',
    },
  ],
  alignment: {
    csv: 'alignment.csv',
    referenceTimeColumn: 'score_time_sec',
    referenceTimeColumnSync: 'synced_time_sec',
    outOfRange: 'clamp',
  },
  features: {
    muteOtherPlayerInstances: true,
    globalVolume: true,
    trackVolumeControls: true,
    trackPanControls: true,
    repeat: false,
    tabView: false,
    iosAudioUnlock: true,
    keyboard: true,
    looping: true,
    seekBar: true,
    timer: true,
    presets: false,
    customizablePanelOrder: false,
  },
});

TrackSwitch.createTrackSwitchSyncInteractive(rootElement, {
  workerUrl: 'dist/js/trackswitch-interactive-worker.js',
});

Configuration

ui

ui is required. It decides which sections appear in the player and in what order they appear.

Use it to add any of these section types:

• trackGroup
• image
• perTrackImage
• text
• waveform
• midi
• sheetMusic
• warpingMatrix

At least one trackGroup section is required because that is where the tracks live.

presetNames

Use presetNames to create ensembles and name your track combinations.

Example:

presetNames: ['Full Mix', 'Vocals Only', 'Backing Track']

Notes:

• Preset numbers start at 0.
• Presets only appear in the ui when you have at least two usable preset choices.
• Tracks decide which presets they belong to through each track’s presets setting.
• If you use presets, presetNames assigns names to preset IDs in numerical order.
• If features.exclusiveSolo is true, presets are disabled.

features

Unknown feature keys are rejected.

alignment

Use alignment only with sync or interactive sync modes. Default-mode players reject this block.

Track Settings

trackGroup

Use type: 'trackGroup' to add one or more tracks to the player.

Example:

{
  type: 'trackGroup',
  rowHeight: 44,
  trackGroup: [
    {
      title: 'Drums',
      image: 'drums.png',
      presets: [0, 2],
      sources: [{ src: 'drums.mp3' }],
    },
  ],
}

Section options:

Notes:

• You can use more than one trackGroup section.
• ui order controls where each trackGroup appears on the page.

Track Options

Each entry inside trackGroup can use these options:

Audio Source Options

Each entry inside sources and alignment.synchronizedSources can use these options:

Notes:

• Every track needs at least one src.
• If you list several source files, the player uses the first one that works for the listener’s browser.
• If type is omitted and the file extension is not in the table above, the player asks the browser about audio/<extension>.

Track Alignment Options

In sync mode, each track can also use an alignment block:

trackGroup: [
    {
      title: 'Track 1',
      sources: [{ src: 'track1.mp3' }],
      alignment: {
        column: 'track_1_time',
        synchronizedSources: [{ src: 'track1-synced.mp3' }],
      }
    },
  ],

Notes:

• synchronizedSources are what make mixed synced playback possible.
• Sync is only available when the player also has a shared sync timeline through referenceTimeColumnSync.

Visualizations

text

Use type: 'text' to add a plain text section to the player.

Example:

{
  type: 'text',
  text: 'Choose which parts of the arrangement you want to hear.',
  bold: true,
  italic: false,
  fontSize: 18,
  align: 'center',
  style: 'margin: 12px 0;',
}

Section options:

Notes:

• The text is plain text only. It is not interpreted as HTML.

image

Use type: 'image' for one main image, such as cover art, a diagram, or a screenshot.

Example:

{
  type: 'image',
  src: 'cover.jpg',
  seekable: true,
  seekMarginLeft: 5,
  seekMarginRight: 5,
  style: 'margin: 12px auto;',
}

Section options:

perTrackImage

Use type: 'perTrackImage' to show the image for the currently active track.

Example:

{
  type: 'perTrackImage',
  seekable: false,
  style: 'margin: 12px auto;',
}

Section options:

Notes:

• Only works if exclusiveSolo is true.
• This section uses each track’s image attribute.

waveform

Use type: 'waveform' to show an interactive waveform.

Example:

{
  type: 'waveform',
  height: 150,
  waveformBarWidth: 2,
  maxZoom: 5,
  waveformSource: 'audible',
  playbackFollowMode: 'center',
  timer: true,
  style: 'margin: 16px 0;',
}

Section options:

Notes:

• If you leave out timer, the waveform timer is off in a standard player and on in a sync player.
• When listeners zoom in, the waveform shows a small overview map for quick navigation.

midi

Use type: 'midi' to show a MIDI file as a piano-roll visualization. MIDI files are only visual; they do not add playback tracks or change audio output.

Example:

{
  type: 'midi',
  src: 'notes.mid',
  alignmentColumn: 'time_notes',
  height: 180,
  maxZoom: 5,
  playbackFollowMode: 'center',
  timer: true,
  style: 'margin: 16px 0;',
}

Section options:

Notes:

• MIDI note timing is read directly from the file in seconds. Standard players use the main player timeline; sync players use the MIDI file duration as the MIDI view’s local timeline.
• The visible pitch range is calculated from the notes in the file with two semitones of padding above and below.
• Clicking or dragging the MIDI view seeks the audio player, like waveform sections.
• MIDI files with no note events are treated as load errors.

sheetMusic

Use type: 'sheetMusic' to show a MusicXML score.

Example:

{
  type: 'sheetMusic',
  src: 'score.musicxml',
  measureColumn: 'measure',
  maxWidth: 960,
  maxHeight: 360,
  renderScale: 0.75,
  followPlayback: true,
  cursorColor: '#999999',
  cursorAlpha: 0.1,
  style: 'margin: 20px auto;',
}

Section options:

Notes:

• If measureColumn is set and matching alignment data is available, listeners can click measures to jump through the music.
• In a standard player, measureColumn can use init.alignment as timing CSV metadata for score following. Full alignment features such as track alignment, aligned waveform overlays, and warping matrices still require the sync player.

warpingMatrix

Use type: 'warpingMatrix' to show interactive warping path and local tempo deviation graphs in sync mode.

Example:

{
  type: 'warpingMatrix',
  height: 240,
  tempoSmoothingSeconds: 5,
  bpm: 'infer_score',
  style: 'margin: 12px 0;',
}

Section options:

Notes:

• This section is only useful in sync mode.
• It shows two views: the timing relationship between the active track and the reference timeline, and the local tempo deviation of the active track over time.
• This section is only enabled when synchronized playback is off in sync mode.
• bpm: 'infer_score' requires at least one sheetMusic ui element in the player.
• Positive height, tempoSmoothingSeconds, and numeric bpm values are used as given. Invalid values are ignored.

Keyboard and Loop Controls

When features.keyboard is on, you can use keyboard shortcuts:

When features.looping is on, you can also use:

Looping is also available through the loop buttons. On seekable controls, loop regions can be marked directly using right-click on mouse.

Things to Check

• ui must contain at least one trackGroup.
• Every track must have at least one audio file in sources.
• Seekable image, perTrackImage, and waveform sections need seekMarginLeft + seekMarginRight to stay below 100.
• perTrackImage is meant for setups where one track is active at a time (exclusiveSolo: true).
• Presets are only shown in the UI when you have at least two preset choices.
• sheetMusic.measureColumn only works for clickable measure syncing when matching alignment data is also available.
• warpingMatrix works only when synchronized playback is off in sync mode, not default mode.
• In sync mode, each track needs its own alignment.column.