Identifiers

Identifiers assign canonical external identities to tracks, artists, and albums. They are the mechanism that lets attribute sources and ephemeral sources link Pipe Bomb entities to external databases.

What is an identity?

An identity is an (identityId, identity) pair:

  • identityId - which identifier produced this identity (e.g., "musicbrainz_album_id")
  • identity - the external ID value (e.g., a MusicBrainz MBID)

A single entity can accumulate identities from multiple identifiers. Identities are stored persistently and will exist until the identifier runs again for a given entity and returns a different result.

Why identifiers matter

Without identifiers, attribute sources have only filename-level information (tags, path). With identifiers, a source can look up a track's MusicBrainz ID and fetch rich metadata from external APIs. Ephemeral sources use identities to merge external tracks with locally-indexed equivalents.

Entity merging

Identities are used to automatically merge artists and albums. If two entities have the identity, they are combined into one. This is how Pipe Bomb builds artist profiles over multiple platforms.

Identifier types

Interface Target
TrackIdentifier Identifies tracks; target is "track", "artist", or "album"
ArtistIdentifier Identifies artists
AlbumIdentifier Identifies albums; target is "artist" or "album"

The target field on track and album identifiers controls which entity the resulting identity is stored against - this allows a track identifier to also produce an artist or album identity as a side effect of its lookup.

Dependencies

Identifiers declare hard and soft dependencies on other identifiers:

  • Hard dependency (getDependencies()) - this identifier only runs after the listed identifiers have completed and their identities are available
  • Soft dependency (getSoftDependencies()) - this identifier prefers to run after the listed identifiers but will run regardless

This lets you chain identifiers: e.g., a MusicBrainz track identifier depends on a basic ISRC identifier that extracts the ISRC from the file's tags.

Running identification

Identification is triggered by the appropriate task. It can be automated by using these tasks in a workflow.

  • Identify Tracks
  • Identify Artists
  • Identify Albums