Interface ExtensionAPI

The API exposed to extensions

interface ExtensionAPI {
    addPlaylist(playlist: Playlist): string;
    addSongs(songs: Song[]): void;
    addToPlaylist(req: AddToPlaylistRequest): void;
    getCurrentSong(): Song;
    getPlayerState(): PlayerState;
    getPreference<T>(data: PreferenceData<T>): T;
    getQueue(): Song[];
    getSecure<T>(data: PreferenceData<T>): T;
    getSong(options: SongAPIOptions): Song[];
    getTime(): number;
    getVolume(): number;
    on(event: "getAccounts", cb: () => AccountDetails[]): void;
    on(
        event: "performAccountLogin",
        cb: (args: AccountLoginArgs) => string,
    ): void;
    on(event: "oauthCallback", cb: (code: string) => void): void;
    on(event: "scrobble", cb: (song: Song) => void): void;
    on(event: "onPlaylistRemoved", cb: (playlist: Playlist) => void): void;
    on(event: "onPlaylistAdded", cb: (playlist: Playlist) => void): void;
    on(event: "onSongRemoved", cb: (song: Song) => void): void;
    on(event: "onSongAdded", cb: (song: Song) => void): void;
    on(event: "onPreferencesChanged", cb: (args: PreferenceArgs) => void): void;
    on(event: "onSeeked", cb: (time: number) => void): void;
    on(event: "onSongChanged", cb: (song: Song) => void): void;
    on(event: "onPlayerStateChanged", cb: (state: PlayerState) => void): void;
    on(event: "onQueueChanged", cb: (queue: unknown) => void): void;
    on(event: "onVolumeChanged", cb: (volume: number) => void): void;
    on(event: "getProviderScopes", cb: () => ProviderScope[]): void;
    on(event: "getPlaylists", cb: () => Promise<PlaylistsReturnType>): void;
    on(
        event: "getPlaylistContent",
        cb: (id: string, token?: string) => Promise<SongsWithPageTokenReturnType>,
    ): void;
    on(
        event: "getPlaylistFromUrl",
        cb: (url: string) => Promise<PlaylistAndSongsReturnType>,
    ): void;
    on(
        event: "getPlaybackDetails",
        cb: (song: Song) => Promise<PlaybackDetailsReturnType>,
    ): void;
    on(event: "search", cb: (term: string) => Promise<SearchReturnType>): void;
    on(
        event: "getRecommendations",
        cb: () => Promise<RecommendationsReturnType>,
    ): void;
    on(
        event: "getSongFromUrl",
        cb: (url: string) => Promise<SongReturnType>,
    ): void;
    on(
        event: "handleCustomRequest",
        cb: (url: string) => Promise<CustomRequestReturnType>,
    ): void;
    on(
        event: "getArtistSongs",
        cb: (
            artist: Artist,
            token?: string,
        ) => Promise<SongsWithPageTokenReturnType>,
    ): void;
    on(
        event: "getAlbumSongs",
        cb: (
            album: Album,
            token?: string,
        ) => Promise<SongsWithPageTokenReturnType>,
    ): void;
    on(
        event: "getSongFromId",
        cb: (id: string) => Promise<SongReturnType>,
    ): void;
    on(
        event: "getSongContextMenu",
        cb: (songs: Song[]) => Promise<ContextMenuReturnType>,
    ): void;
    on(
        event: "getPlaylistContextMenu",
        cb: (playlist: Playlist) => Promise<ContextMenuReturnType>,
    ): void;
    on(
        event: "onContextMenuAction",
        cb: (action: string) => Promise<void>,
    ): void;
    on(event: "getLyrics", cb: (song: Song) => Promise<string>): void;
    openExternalUrl(url: string): void;
    registerOAuth(token: string): void;
    removeSong(song: Song): void;
    setPreference<T>(data: PreferenceData<T>): void;
    setSecure<T>(data: PreferenceData<T>): void;
    updateAccounts(): void;
    updateSong(song: Song): void;
}

Methods

addPlaylist addSongs addToPlaylist getCurrentSong getPlayerState getPreference getQueue getSecure getSong getTime getVolume on openExternalUrl registerOAuth removeSong setPreference setSecure updateAccounts updateSong

Methods

addPlaylist

  • addPlaylist(playlist: Playlist): string

    Adds a new playlist to the main app.

    Parameters

    Returns string

    The ID of the added playlist

addSongs

  • addSongs(songs: Song[]): void

    Adds a list of songs to the main app.

    Parameters

    • songs: Song[]

      The songs to add

    Returns void

addToPlaylist

getCurrentSong

  • getCurrentSong(): Song

    Retrieves the current song being played.

    Returns Song

    The current song or undefined if no song is playing

getPlayerState

  • getPlayerState(): PlayerState

    Retrieves the current state of the player.

    Returns PlayerState

    The current player state

getPreference

  • getPreference<T>(data: PreferenceData<T>): T

    Retrieves a preference value based on the provided data.

    Type Parameters

    • T

    Parameters

    • data: PreferenceData<T>

      The preference data containing key and optional default value

    Returns T

    The preference value

getQueue

  • getQueue(): Song[]

    Retrieves the current playback queue.

    Returns Song[]

    An array of songs in the current queue

getSecure

  • getSecure<T>(data: PreferenceData<T>): T

    Retrieves a secure preference value based on the provided data.

    Type Parameters

    • T

    Parameters

    • data: PreferenceData<T>

      The preference data containing key and optional default value

    Returns T

    The secure preference value

getSong

getTime

  • getTime(): number

    Retrieves the current playback time.

    Returns number

    The current playback time in seconds

getVolume

  • getVolume(): number

    Retrieves the current volume level.

    Returns number

    The current volume level between 0 and 1

on

  • on(event: "getAccounts", cb: () => AccountDetails[]): void

    Called when the main app requests the list of accounts.

    Parameters

    • event: "getAccounts"

      Event name

    • cb: () => AccountDetails[]

      Callback that returns the list of accounts

    Returns void

  • on(event: "performAccountLogin", cb: (args: AccountLoginArgs) => string): void

    Called when the main app requests to perform an account login.

    Parameters

    • event: "performAccountLogin"

      Event name

    • cb: (args: AccountLoginArgs) => string

      Callback that handles the login request

    Returns void

  • on(event: "oauthCallback", cb: (code: string) => void): void

    Called when the main app provides an OAuth callback code.

    Parameters

    • event: "oauthCallback"

      Event name

    • cb: (code: string) => void

      Callback that handles the OAuth code

    Returns void

  • on(event: "scrobble", cb: (song: Song) => void): void

    Called when the main app requests to scrobble a song.

    Parameters

    • event: "scrobble"

      Event name

    • cb: (song: Song) => void

      Callback that handles the scrobble request

    Returns void

  • on(event: "onPlaylistRemoved", cb: (playlist: Playlist) => void): void

    Called when a playlist is removed from the database.

    Parameters

    • event: "onPlaylistRemoved"

      Event name

    • cb: (playlist: Playlist) => void

      Callback that receives the removed playlist

    Returns void

  • on(event: "onPlaylistAdded", cb: (playlist: Playlist) => void): void

    Called when a playlist is added to the database.

    Parameters

    • event: "onPlaylistAdded"

      Event name

    • cb: (playlist: Playlist) => void

      Callback that receives the added playlist

    Returns void

  • on(event: "onSongRemoved", cb: (song: Song) => void): void

    Called when a song is removed from the database.

    Parameters

    • event: "onSongRemoved"

      Event name

    • cb: (song: Song) => void

      Callback that receives the removed song

    Returns void

  • on(event: "onSongAdded", cb: (song: Song) => void): void

    Called when a song is added to the database.

    Parameters

    • event: "onSongAdded"

      Event name

    • cb: (song: Song) => void

      Callback that receives the added song

    Returns void

  • on(event: "onPreferencesChanged", cb: (args: PreferenceArgs) => void): void

    Called when preferences are changed.

    Parameters

    • event: "onPreferencesChanged"

      Event name

    • cb: (args: PreferenceArgs) => void

      Callback that receives the changed preference

    Returns void

  • on(event: "onSeeked", cb: (time: number) => void): void

    Called when the player is seeked to a specific time.

    Parameters

    • event: "onSeeked"

      Event name

    • cb: (time: number) => void

      Callback that receives the new playback time

    Returns void

  • on(event: "onSongChanged", cb: (song: Song) => void): void

    Called when the song is changed.

    Parameters

    • event: "onSongChanged"

      Event name

    • cb: (song: Song) => void

      Callback that receives the new song

    Returns void

  • on(event: "onPlayerStateChanged", cb: (state: PlayerState) => void): void

    Called when the player state is changed.

    Parameters

    • event: "onPlayerStateChanged"

      Event name

    • cb: (state: PlayerState) => void

      Callback that receives the new player state

    Returns void

  • on(event: "onQueueChanged", cb: (queue: unknown) => void): void

    Called when the queue is changed.

    Parameters

    • event: "onQueueChanged"

      Event name

    • cb: (queue: unknown) => void

      Callback that receives the new queue

    Returns void

  • on(event: "onVolumeChanged", cb: (volume: number) => void): void

    Called when the volume is changed.

    Parameters

    • event: "onVolumeChanged"

      Event name

    • cb: (volume: number) => void

      Callback that receives the new volume

    Returns void

  • on(event: "getProviderScopes", cb: () => ProviderScope[]): void

    Called when the main app requests the provider scopes.

    Parameters

    • event: "getProviderScopes"

      Event name

    • cb: () => ProviderScope[]

      Callback that returns the provider scopes

    Returns void

  • on(event: "getPlaylists", cb: () => Promise<PlaylistsReturnType>): void

    Called when the main app requests the list of playlists.

    Parameters

    • event: "getPlaylists"

      Event name

    • cb: () => Promise<PlaylistsReturnType>

      Callback that returns the playlists

    Returns void

  • on(
        event: "getPlaylistContent",
        cb: (id: string, token?: string) => Promise<SongsWithPageTokenReturnType>,
    ): void

    Called when the main app requests the content of a specific playlist.

    Parameters

    • event: "getPlaylistContent"

      Event name

    • cb: (id: string, token?: string) => Promise<SongsWithPageTokenReturnType>

      Callback that returns the playlist content

    Returns void

  • on(
        event: "getPlaylistFromUrl",
        cb: (url: string) => Promise<PlaylistAndSongsReturnType>,
    ): void

    Called when the main app requests a playlist from a URL.

    Parameters

    • event: "getPlaylistFromUrl"

      Event name

    • cb: (url: string) => Promise<PlaylistAndSongsReturnType>

      Callback that returns the playlist and its songs

    Returns void

  • on(
        event: "getPlaybackDetails",
        cb: (song: Song) => Promise<PlaybackDetailsReturnType>,
    ): void

    Called when the main app requests playback details for a song.

    Parameters

    Returns void

  • on(event: "search", cb: (term: string) => Promise<SearchReturnType>): void

    Called when the main app performs a search.

    Parameters

    • event: "search"

      Event name

    • cb: (term: string) => Promise<SearchReturnType>

      Callback that returns the search results

    Returns void

  • on(
        event: "getRecommendations",
        cb: () => Promise<RecommendationsReturnType>,
    ): void

    Called when the main app requests recommendations.

    Parameters

    Returns void

  • on(event: "getSongFromUrl", cb: (url: string) => Promise<SongReturnType>): void

    Called when the main app requests a song from a URL.

    Parameters

    • event: "getSongFromUrl"

      Event name

    • cb: (url: string) => Promise<SongReturnType>

      Callback that returns the song

    Returns void

  • on(
        event: "handleCustomRequest",
        cb: (url: string) => Promise<CustomRequestReturnType>,
    ): void

    Called when the main app handles a custom request.

    Parameters

    • event: "handleCustomRequest"

      Event name

    • cb: (url: string) => Promise<CustomRequestReturnType>

      Callback that handles the custom request

    Returns void

  • on(
        event: "getArtistSongs",
        cb: (
            artist: Artist,
            token?: string,
        ) => Promise<SongsWithPageTokenReturnType>,
    ): void

    Called when the main app requests songs of a specific artist.

    Parameters

    Returns void

  • on(
        event: "getAlbumSongs",
        cb: (album: Album, token?: string) => Promise<SongsWithPageTokenReturnType>,
    ): void

    Called when the main app requests songs of a specific album.

    Parameters

    Returns void

  • on(event: "getSongFromId", cb: (id: string) => Promise<SongReturnType>): void

    Called when the main app requests a song from an ID.

    Parameters

    • event: "getSongFromId"

      Event name

    • cb: (id: string) => Promise<SongReturnType>

      Callback that returns the song

    Returns void

  • on(
        event: "getSongContextMenu",
        cb: (songs: Song[]) => Promise<ContextMenuReturnType>,
    ): void

    Called when the main app requests the context menu for songs.

    Parameters

    • event: "getSongContextMenu"

      Event name

    • cb: (songs: Song[]) => Promise<ContextMenuReturnType>

      Callback that returns the context menu items

    Returns void

  • on(
        event: "getPlaylistContextMenu",
        cb: (playlist: Playlist) => Promise<ContextMenuReturnType>,
    ): void

    Called when the main app requests the context menu for a playlist.

    Parameters

    • event: "getPlaylistContextMenu"

      Event name

    • cb: (playlist: Playlist) => Promise<ContextMenuReturnType>

      Callback that returns the context menu items

    Returns void

  • on(event: "onContextMenuAction", cb: (action: string) => Promise<void>): void

    Called when the main app performs an action from the context menu.

    Parameters

    • event: "onContextMenuAction"

      Event name

    • cb: (action: string) => Promise<void>

      Callback that handles the action

    Returns void

  • on(event: "getLyrics", cb: (song: Song) => Promise<string>): void

    Called when the main app requests lyrics for a song.

    Parameters

    • event: "getLyrics"

      Event name

    • cb: (song: Song) => Promise<string>

      Callback that returns the lyrics

    Returns void

openExternalUrl

  • openExternalUrl(url: string): void

    Opens an external URL.

    Parameters

    • url: string

      The URL to open

    Returns void

registerOAuth

  • registerOAuth(token: string): void

    Registers an OAuth token with the main app.

    Parameters

    • token: string

      The OAuth token to register

    Returns void

removeSong

  • removeSong(song: Song): void

    Removes a song from the main app.

    Parameters

    • song: Song

      The song to remove

    Returns void

setPreference

  • setPreference<T>(data: PreferenceData<T>): void

    Sets a preference value based on the provided data.

    Type Parameters

    • T

    Parameters

    Returns void

setSecure

  • setSecure<T>(data: PreferenceData<T>): void

    Sets a secure preference value based on the provided data.

    Type Parameters

    • T

    Parameters

    Returns void

updateAccounts

  • updateAccounts(): void

    Updates the list of accounts in the main app.

    Returns void

updateSong

  • updateSong(song: Song): void

    Updates a song in the main app.

    Parameters

    • song: Song

      The song to update

    Returns void

Settings

Member Visibility

On This Page

Methods