Variable libraryConst

Type Declaration

• addToPlaylist: (
      paths: string[],
      playlist?: PlaylistRef,
  ) => Promise<LibraryAddToPlaylistResponse>

  Append paths to a playlist, by default the active one. Pass the playlist's guid rather than its index when the playlist list may change between choosing the target and the call, for example while a menu is open.

• browseDirectory: (
      path: string,
      includeFiles?: boolean,
  ) => Promise<LibraryBrowseDirectoryResponse>

  Browse a directory path on disk within the media library.

• browseTree: (params: LibraryBrowseTreeParams) => Promise<LibraryBrowseTreeResponse>

  Browse the logical library hierarchy starting from a root folder.

• enumerateDirectories: (
      options?: LibraryEnumerateDirectoriesOptions,
  ) => AsyncGenerator<
      LibraryDirectoryBatch,
      LibraryEnumerateDirectoriesSummary,
      void,
  >

  Async generator that walks library directories breadth- or depth-first via the library.browseDirectory endpoint.

  Deprecated

  Prefer library.enumerateTree for root-aware traversal.

• enumerateFieldValues: (
      field: string,
      options?: LibraryEnumerateFieldValuesOptions,
  ) => Promise<LibraryGetFieldValuesResponse>

  Semantic alias for library.getFieldValues.

• enumerateTracks: (
      options?: LibraryEnumerateTracksOptions,
  ) => AsyncGenerator<
      LibraryEnumerateTracksPage,
      LibraryEnumerateTracksSummary,
      void,
  >

  Async generator that pages through every track in the library. Honours signal for cooperative cancellation and emits a progress callback after each page fetch.

• enumerateTree: (
      options: LibraryEnumerateTreeOptions,
  ) => AsyncGenerator<LibraryTreeBatch, LibraryEnumerateTreeSummary, void>

  Async generator that walks the typed library tree starting at a given rootId. Failed nodes are skipped (still counted) so a partial outage does not abort the traversal.

• getAlbums: (options?: number | LibraryGetAlbumsParams) => Promise<LibraryGetAlbumsResponse>

  List albums across the library, grouped by album name plus album artist. Tracks without an album tag are skipped.

• getAlbumTracks: (
      album: string,
      albumArtist: string,
      options?: Pick<LibraryGetAlbumTracksParams, "albumId">,
  ) => Promise<LibraryGetAlbumTracksResponse>

  Tracks of one album from getAlbums, sorted by disc number, then track number, then library order.

  Pass the row's name and albumArtist as they are. Without albumId, both are compared byte for byte, and total equals the row's trackCount. The row's artist is not the same key, and an album artist that is "" must be passed as "". A pair no row has resolves with no tracks and no row. The grouping is kept by the host until the library changes, so repeated calls do not rescan the library.

  When the row supplies albumId, pass it in options to identify the original album rather than its display names. An empty or malformed ID fails with INVALID_PARAMS; it never falls back to a name lookup.

  Example

  const page = await fb.library.getAlbums({ limit: 1 });
    const album = page.success ? page.albums[0] : undefined;
    if (album) {
        const res = await fb.library.getAlbumTracks(album.name, album.albumArtist, album);
    }
  Copy

• getAll: (
      start?: number,
      count?: number,
      opts?: Pick<LibraryGetAllParams, "useCache" | "asyncResult"> & {
          timeout?: number;
      },
  ) => Promise<ApiFailure | LibraryPagedTracksResponse>

  Fetch library tracks: count tracks from position start, sent as the host's offset and limit (host defaults 0 and 100). Resolves synchronously for paged requests and cache hits.

  Options:

  • useCache — from start 0, answer from the list the host kept after an earlier request from 0 that covered every track. Sent only when given; the host default is true. A request from 0 covering every track is kept either way.
  • asyncResult — let the host build a request from 0 that covers every track off the main thread. Defaults to true here (the host's own default is false); it takes effect only with useCache and not when the kept list answers. The host then answers { pending: true, requestId } and delivers the page as the library:getAllResult event; this wrapper listens for that event before sending the call, so an early delivery is not missed, and resolves with the page. Pass false to have the host build the page on the main thread.
  • timeout — milliseconds to wait for the event, default 60 000; 0 or less waits indefinitely.

  Either way it resolves with a LibraryPagedTracksResponse or an ApiFailure, so callers are unaffected by the threading model. A failure envelope from the call resolves as it is. A list the host failed to build and a timeout both resolve with OPERATION_FAILED; details.requestId names the request, and a timeout also carries details.timeoutMs. The returned promise rejects only when the call itself rejects. The event listener is removed in every case.

• getArtistAlbums: (
      artist: string,
      limit?: number,
      options?: Omit<LibraryGetArtistAlbumsParams, "artist" | "limit">,
  ) => Promise<LibraryGetArtistAlbumsResponse>

  Albums an artist appears on, as rows shaped like library.getAlbums.

  artist is compared byte for byte against each atomic tag value, so a name taken from getArtists also matches tracks where it is not the first of several credited artists, and an artist differing only in case is never pulled in. Pass one artist name: on a multi-value track the joined track.artist string matches nothing, and on a single-value track it happens to equal the atomic value, so it is not a key you can rely on. Pass match: 'substring' to match on containment instead, which also returns albums by any other artist whose name contains the argument; that mode is looser about case, matching either case wherever the argument is lowercase.

  trackCount, duration and discCount count only the tracks this artist appears on, not the whole album — getAlbums returns the album-wide figures for the same row. Rendering a row here as an album card will therefore understate it. The row's tracks, when present, identify those contributing members; use them instead of display names to distinguish equal-looking rows.

  Rows are grouped by album name alone, so identically titled albums by different artists collapse into one row; tracks whose album tag is missing are grouped under (Unknown Album) rather than dropped. Both differ from getAlbums, which keys on album plus album artist and skips tracks with no album. Cover art is not inlined: pass firstTrackAbsolutePath to artwork.getForTrack, since firstTrackPath can be a file-relative:// URI that endpoint refuses.

  There is no offset: when hasMore is true the only way to see the rest is a larger limit.

• getArtists: (
      limit?: number,
      options?: Omit<LibraryGetArtistsParams, "limit">,
  ) => Promise<LibraryGetArtistsResponse>

  List credited artists with per-artist aggregates.

  options.includeAlbums adds an albums array to every row — the (name, artist) identities of the albums that artist is credited on, so an "artist → albums" section can be built from one call instead of one getArtistAlbums scan per artist. limit caps the rows, never the albums inside them.

• getArtistTracks: (artist: string, limit?: number) => Promise<LibraryGetArtistTracksResponse>

  Tracks an artist appears on.

  artist is matched exactly as in getArtistAlbums under match: 'exact': compared byte for byte against each atomic tag value, so a name from getArtists matches even when it is not the first of several credited artists, and an artist differing only in case is never pulled in.

• getByPath: (path: string) => Promise<LibraryGetByPathResponse>

  Look up one file in the library and return its track metadata.

• getCacheStats: () => Promise<LibraryGetCacheStatsResponse>

  Report diagnostic cache hit/miss statistics for library queries and indexes.

• getChanges: (params?: LibraryGetChangesParams) => Promise<LibraryGetChangesResponse>

  Fetch the library revision and tracks changed after since for local incremental sync. Pass previous epoch and revision; when omitted or mismatched, returns resync: true with full handles. Fails with OPERATION_PENDING while the library is still loading.

• getCount: () => Promise<LibraryGetCountResponse>

  Report the total number of tracks in the library.

• getFieldValues: (
      field: string,
      limit?: number,
      separator?: string,
  ) => Promise<LibraryGetFieldValuesResponse>

  Report every distinct value of one metadata tag across the library with track counts.

• getGenres: () => Promise<LibraryGetGenresResponse>

  Report every genre in the library with its track count, ordered by name.

• getRandomTracks: (count?: number) => Promise<LibraryGetRandomTracksResponse>

  Draw tracks at random from the whole library without duplicates.

• getRecentlyAdded: (
      limit?: number,
      sortBy?: "added" | "modified",
  ) => Promise<LibraryGetRecentlyAddedResponse>

  Report the most recently added tracks of the library.

• getRoots: () => Promise<LibraryGetRootsResponse>

  Report the library's root folders.

• getStats: () => Promise<LibraryGetStatsResponse>

  Report aggregate track, album, and artist counts over the whole library.

• getStatus: () => Promise<LibraryGetStatusResponse>

  Report whether the library is enabled and how many tracks it holds.

• getTracks: (handles: string[], fields?: string[]) => Promise<LibraryGetTracksResponse>

  Fetch library rows for up to 5000 handles in the given order. Missing handles are reported in missing. Optional fields restricts row keys, as in library.query.

• invalidateCache: () => Promise<LibraryInvalidateCacheResponse>

  Invalidate cached library query results and directory tree indexes.

• isEnabled: () => Promise<LibraryIsEnabledResponse>

  Report whether the foobar2000 media library is enabled.

• query: (
      query: string,
      sort?: string,
      limit?: number,
      fields?: string[],
  ) => Promise<LibraryQueryResponse>

  Run a foobar2000 query expression with an optional Title Formatting sort expression. Sorting is applied before limit truncation and total reports the untruncated hit count.

  fields narrows the rows exactly as documented on library.search.

• refresh: () => Promise<LibraryRefreshResponse>

  Ask foobar2000 to rescan the library folders.

• rescan: () => Promise<LibraryRescanResponse>

  Request foobar2000 to rescan the configured library folders.

• search: (
      query: string,
      limit?: number,
      options?: Omit<LibrarySearchParams, "limit" | "query">,
  ) => Promise<LibrarySearchResponse>

  Run a foobar2000 query expression against the media library.

  options.offset / limit page the hit list; total and hasMore report the full extent. options.fields narrows each row to the named keys of a library track row, which is why rows are typed as LibraryTrackPartial. An unknown name resolves — never rejects — with { success: false, code: 'INVALID_PARAMS' } and the names under details.unknownFields.