The Digger Manual

Getting the most from your annotated music collection.

Where Digger finds your music

After you grant permission to access your music, Digger uses an MPMediaQuery to ask iOS for all songs available for apps on your device. To copy songs onto your device, use Apple Music to sync all or part of your collection from your computer.

After you grant permission to access your music, Digger queries the Android MediaStore for available music audio. To copy songs onto your device, use the Android File Transfer app from your computer.

Digger creates .digger_config.json in your home directory with a default musicPath set to the Music folder off your home directory. To change where Digger should find music, click the library button () at the top center of the app, then choose "Music Files" to set where Digger should look. If there are folders Digger should avoid, use the "Ignore Folders" button under the library options to tell Digger what to skip over. Folder names can end with an asterisk ('*') wildcard.

Digger relies on song file metadata for search and sync. While it may be able to guess missing metadata from an Artist/Album/Song file organization, any missing metadata in your collection should be fixed using a tool for that purpose. Each song must have a title and artist. Digger does not modify your song files.

Where Digger saves your annotations

Digger saves your annotations in the app. You can sync your annotations to DiggerHub for backup and access from multiple devices. Click the "Digger" link in the upper left of the app to sign in and enable sync.

Digger saves your annotations in the app. You can sync your annotations to DiggerHub for backup and access from multiple devices. Click the "Digger" link in the upper left of the app to sign in and enable sync.

Digger saves your annotations as digdat.json in your home folder. To change where Digger saves your annotations, click the library button at the top center of the app, then choose Digger Data to set where Digger should save your annotations. You can sync your annotations to DiggerHub for backup and access from multiple devices. Click the "Digger" link in the upper left of the app to sign in and enable sync.

Autoplay, Albums and Search

On first launch, Digger starts with the (Album) display and provides suggestions. If you have something else in mind, use the (Search) display. To play individual songs, use the (Deck) display. After initial launch, the app resumes whichever display you were last in. The song to play next follows the display you have active.

Digger always prefers what you have least recently heard, so it will dig through the stacks in your collection and pull things you might want to hear next. As you listen, you can annotate what's playing, then you can reference your annotations for selecting songs.

Annotating a song

Digger annotations capture an almost complete picture of your impression of a song, saving a rating that can be used for music retrieval. You record your impression using the feel knobs, keyword toggles, star bar and comment entry.

Feel knobs let you position a song along a dimension of the music universe. Digger supports two dimensions: Approachability and Energy Level. How you position each of these knobs depends entirely on your feelings and what the values mean to you. Perhaps "Easy" might reflect soothing, consonance, or simplicity whereas "Hard" might indicate challenging, dissonance, or complexity. Perhaps "Chill" might reflect slow, quiet, or relaxing, whereas "Amped" might indicate fast, loud, or activating. Whatever you feel.

Keyword toggles let you mark a song for retrieval using categorical and situational tags. The default tags have been chosen through trials to yield excellent selection power for minimum data entry. As an example the "Social" keyword, with a feel knob value, can mark presentation music from a low key brunch to an energetic party. Expand the keyword toggles to see or add more.

The star bar lets you reflect if a song is better or less than average for your collection. The expectation is everything in your collection was worth keeping, so lower rated songs are typically less impressive tracks from otherwise notable albums, and top rated songs could be personal anthems.

The comment button opens text input for your notes about a song or what it means to you. Digger comments are a sentence or short paragraph, if a song merits a longer discussion or story, that's best posted separately. You can include a URL in your comment, but it may not be clickable in the app. All text in comments is available to search, so words and phrases you write work for search.

The share button copies all information about the song, including your annotations, to DiggerHub or to the clipboard for sharing using whatever social tech you like. The sleep button is an extended transport control allowing you to pause playback after a song finishes.

Tuning Options

Digger won't generally play a song that was previously played within 24 hours, but some songs might still feel like they get pulled too often. By marking a song as Tired, the playback frequency switches from 'P' (playable) to 'B' (backburner) meaning it will be played at most once every 90 days. If you skip a backburner song it automatically moves to 'Z' (sleeper) and plays at most once every 180 days. If you skip a sleeper song it moves to 'O' (overplayed) and is eligible to play once a year.

If a song has autoplayed enough for a lifetime, or if it doesn't stand on its own outside of its album context, "Don't Suggest" will disqualify it from autoplay selection.

If the keywords you've selected for the currently playing song can be applied to all songs on the album, ⇨ Album will add or overwrite those keywords across all album songs.

The tuning display also shows the source of the currently playing song, the last playback time (if previously played), and a dupes count (if dupes are found). Digger marks duplicate songs as played so you don't get the same song repeatedly suggested from a compilation, the original album, and wherever else. Dupe tracking works off matching song metadata, so Digger might still pull the remix version of a song even if you played the original.

Filtering songs for playback

In Deck playback mode, Digger shows the song retrieval filters and the selected songs "on deck" for playback. The retrieval filters determine currently acceptable knob values, keywords, and rating stars across songs in your collection.

2D range selectors allow you to specify an acceptable Feel Knob range and bounding using a single motion. All songs that have not been feel adjusted are in the center.

You can filter on up to 4 active keywords at once. To select which keywords are currently active for retrieval, click "Choose Keywords" under the library actions () at the top center of the app. Each active keyword has an associated 3-way toggle allowing you to specify if matching songs must have the keyword, must not have the keyword, or off (may or may not have the keyword).

Default Keywords

"Choose Keywords" under the library actions lets you select which keywords to use for filtering and in what order they should be displayed. You can also remove keywords you don't want to use anymore.

The default keywords have been chosen and tested over a period of years to provide excellent retrieval capabilities with minimum required tagging. The default keywords are:

  • Social: Playable in gatherings with other people.
  • Personal: Special to you.
  • Office: Appropriate while working.
  • Dance: Music to move to.
  • Ambient: Transitionable from or to silence. Listenable at various attention levels.
  • Jazz: As applied to your collection.
  • Classical: As applied to your collection.
  • Talk: Spoken word, conversational attention.
  • Solstice: Seasonal holiday. Whatever you celebrate.

Many other keywords such as "Morning", "Workout", "Commute" etc have fallen by the wayside over time in favor of range controls and more generally useful keys. Highly specific genre categories usually got tedious to maintain but may be useful for specific collections.

Star values are filtered using a 5-way toggle button. "Standard" means 2.5 stars or higher, so it includes all songs that have not had their rating value adjusted from the default initial value. If you want to play just your favorite hits, or delve into the depths, click to adjust accordingly. Digger prefers songs you've least recently listened to, so you'll get fullest possible coverage of your collection at whatever rating level you select.

The normal setting for keyword tag access is "Allow Untagged" which means keyword tag filtering works as you would probably expect. If you only want to play songs that have no associated keywords at all, you can change this to "Untagged Only". The opposite of that is "Tagged Only". Unless you are currently obsessed with tagging all songs in your collection, "Allow Untagged" is probably what you want.

The frequency filtering button is normally on, meaning that Digger will not suggest a song if it was played in the past 24hrs, or longer if it was marked as tired. If you've run out of songs on deck due to frequency filtering, this toggle lets you see which songs would otherwise have been eligible to play.

Viewing and tuning songs on deck

The info () button gives a short summary of how many songs in your collection passed each of the filters. The history () button shows songs you've played before. Clicking any deck song overlays an action bar where you can

Play this song right now.
Play this song next, or after the last song previously bumped to play next.
Skip playing this song.
Verify marked as tired and skip.


Click Digger in the upper left of the app to sign in for backup, sync, and optional structured collaboration.

Digger saves song annotations and playback times to the hub as you listen. If you ever need to install Digger from scratch, just sign in to pull down all your previously synchronized annotation and playback data. If you have a lot of song ratings, you might see the "hub" indicator light staying lit for a little while. Click it to view progress details. A full restore can take a minute or more, but after initial sync, incremental sync operations typically take under a second.

If you like, you can try structured interactions with fellow music fans to find music you have in common, get recommendations for songs you don't have, or fill default info for songs you haven't annotated yet.

Visit DiggerHub for more info.