Tidal Luna Documentation

The Player and SettingsState interfaces control how audio is delivered and how the player interacts with devices.

Player Configuration

Use the Player interface to manage active devices and volume control:

• activeDeviceId: The ID of the currently active device.
• activeDeviceMode: Can be either "exclusive" or "shared".
• availableDevices: A list of PlayerAvailableDevice objects containing id, name, nativeDeviceId, and webDeviceId.

Audio Settings

Use SettingsState to manage user preferences:

• audioNormalization: Set to "NONE", "ALBUM", or "TRACK".
• quality.streaming: Controls the AudioQuality of the stream.
• explicitContentEnabled: Boolean to toggle explicit content.

// Example of Player interface structure
export interface Player {
	activeDeviceId: string;
	activeDeviceMode: PlayerDeviceMode; // "exclusive" | "shared"
	availableDevices: PlayerAvailableDevice[];
	desiredDeviceMode: Record<string, string>;
	forceVolume: Record<string, boolean>;
	hasPreloadedNextProduct: boolean;
}

// Example of SettingsState structure
export interface SettingsState {
	audioNormalization: "NONE" | "ALBUM" | "TRACK";
	audioSpectrumEnabled: boolean;
	autoPlay: boolean;
	desktop: {
		autoStartMode: 0 | 1;
		closeToTray: boolean;
	};
	explicitContentEnabled: boolean;
	language: string;
	openLinksInDesktopApp: boolean;
	quality: { streaming: AudioQuality };
	updateAvailable: boolean;
	urls: Record<string, string>;
}

To create a plugin for Tidal Luna, you must implement a module that exports specific properties. The LunaPlugin class manages the lifecycle (loading, enabling, disabling, unloading) of these modules.

When your plugin is loaded via import(), it can export the following ModuleExports to interact with the Luna runtime:

• unloads?: LunaUnloads: A set of cleanup functions (of type LunaUnload) to be called when the plugin is unloaded.
• onUnload?: LunaUnload: A single cleanup function.
• Settings?: React.FC: A React component used to render the plugin's settings UI.
• errSignal?: Signal<string | undefined>: A signal used to communicate errors from the plugin back to the Luna runtime.

Note on Unloading: It is critical to use the unloads set or onUnload hook to clean up side effects (like event listeners or timers), otherwise, they will leak when the plugin is reloaded or uninstalled.

// Example of what your plugin module (.mjs) should export
export const Settings = ({ data }) => <div>Plugin Settings</div>;

export const onUnload = () => {
  console.log("Cleaning up plugin...");
};

export const errSignal = new Signal<string | undefined>(undefined);

export const unloads = new Set([
  () => { /* cleanup task */ }
]);

The application tracks user identity and connectivity through the SessionState and Auth interfaces.

Session State

SessionState contains metadata about the current client connection:

• userId: The numeric ID of the logged-in user.
• isInitialized: Indicates if the session setup is complete.
• countryCode: The user's current country code.
• utmParameters: Tracking parameters for marketing/campaigns (banner, campaign, content, medium, source).

Authentication

Auth provides the necessary data for the authentication flow:

• verificationUri: The URI used for user verification/login.

export interface SessionState {
	clientId: string;
	clientUniqueKey: string;
	countryCode: string;
	facebookAccessToken?: string | null;
	isInitialized: boolean;
	isLoading: boolean;
	isPolling: boolean;
	userId: number;
	utmParameters: {
		banner: string;
		campaign: string;
		content: string;
		medium: string;
		source: string;
	};
	migrated: boolean;
}

export interface Auth {
	verificationUri: string;
}

The PlayState class provides a static API to control and monitor the current playback state. You can play, pause, skip, seek, and manage the play queue.

Playback Controls

• PlayState.play([mediaItemId]): Plays the current track or a specific track if an ID is provided.
• PlayState.pause(): Pauses playback.
• PlayState.next(): Skips to the next track.
• PlayState.previous(): Skips to the previous track.
• PlayState.moveTo(playQueueIndex): Moves to a specific index in the play queue.
• PlayState.playNext(mediaItemIds): Adds one or more media items to the queue immediately after the current track (these are temporary and removed after playing).
• PlayState.seek(time): Seeks to a specific time in seconds.

Shuffle and Repeat

• PlayState.setShuffle(shuffle, shuffleItems?): Enables or disables shuffle mode. If shuffleItems is true, it will re-shuffle the current items.
• PlayState.setRepeatMode(repeatMode): Sets the repeat mode using redux.RepeatMode values.

// Play a specific track
PlayState.play('some-media-item-id');

// Skip to next
PlayState.next();

// Seek to 30 seconds
PlayState.seek(30);

// Enable shuffle and re-shuffle current queue
PlayState.setShuffle(true, true);