Ephemeral Sources

An ephemeral source is a plugin component that integrates an external music catalog into Pipe Bomb without indexing it locally. Users can search the external source, browse artists and albums, and play tracks - all through the same UI as the local library.

How ephemeral sources work

An ephemeral source implements both a search interface and a streaming interface:

  1. Search - when the user searches, the server calls search(options) on each registered ephemeral source alongside the local search. Results are returned as EphemeralTrack, IdentifiableArtistMetadata, and IdentifiableAlbumMetadata objects.

  2. Streaming - every ephemeral source is tied to a LibraryHandler. When a user plays an ephemeral track, the server uses this handler's getAudioProducer() to stream audio, exactly like a local library.

  3. Resolution - clicking an ephemeral artist or album triggers resolveArtist() / resolveAlbumContent() etc. to fetch their full content from the external source on demand.

Identity matching

Ephemeral sources declare which users/Identifiers they use to match external entities to local ones:

  • resolveArtistIdentifier(identifierId) - the identifier whose output to compare against when linking an ephemeral artist to a local artist
  • resolveAlbumIdentifier(identifierId) - same for albums
  • useTrackIdentifier(identifierId) - the identifier whose output to compare against when linking an ephemeral track to a local track

When a match is found, the frontend merges the ephemeral result with the local entity rather than showing it as a separate result.

Track creation sessions

A user can "save" an ephemeral track to the local library by adding it to a playlist. This opens a track creation session:

  1. The server creates a session with the ephemeral track's metadata
  2. The track is added to the appropriate local library via the ephemeral source's LibraryHandler
  3. Identifiers and attribute sources run against it as they would any scanned track

Importing large quantities of ephemeral tracks at once can take a while because the server requests basic identification and attribution information for each track. You can view this progress on the playlist page that you added the ephemeral tracks to.

Attribute and config integration

Ephemeral sources can use an attribute source (via useAttributeSource() in the EphemeralSourceApiContext) to enrich their results with the same metadata system used by local tracks.