The Digger Manual

Digger is a music library tool for retrieval and collaboration. It works like a mixer for your music collection.

Getting started

When you first start Digger, it reads and saves song information from your library and starts playing music. Digger does not modify your music files or library. If you sign in, song impressions you save in Digger will be synchronized across your devices.

The Player Panel

The player panel holds transport control and song tuning options. The main controls are the Energy Level and Approachability pan knobs. Whether you think of "Amped" as heads-down-amps-on-10, high BPM, massive technical prowess, fireworks and/or whatever else, that's how you think of it. Likewise whether "Chill" means sleep, relaxation, meditation or whatever, that's what you think of that. You might think of "Hard" as dissonance, harsh sounds, tough lyrics or other challenging aspects. By contrast "Easy" might be consonance, familiar sounds, general approachability. Whatever you feel.

Everything in your collection is already above average or you wouldn't have bothered collecting it, but some songs are a bit better or worse relative to the rest. Adjust the rating stars above or below 3 if you want to capture that.

Keyword toggles let you mark the song for retrieval, either by situation or category. Keywords combine with energy level and approachability when digging for music to play. For example you might select "Social" for songs you are comfortable playing when having people over, then adjust energy level and approachability as appropriate for the situation. Click the '+' button to the left to expand all keywords and/or add more.

Use the comment button to save a statement about the song. The snooze button will pause playback after the song finishes.

The skip button in the upper right skips to the next song. The tuning fork to the left of that brings up additional song details and playback options. Generally a song is eligible to play once every 24hrs. If you find a song is being suggested too often, select "Tired" under the tuning options to reduce the eligibility to once every 3 months. If you click skip again after that, eligibility moves to every 6 months. Skip it again and it's once a year. By design, Digger always grabs oldest stuff first, so you might not need this, but it comes in handy for classic songs that might be a bit overplayed.

The Filters Panel

The filters panel controls how Digger pulls from your library. The Energy Level and Approachability range controls each have a slider on the left to change the width of the retrieval range, and a slider at the bottom to adjust the position of the retrieval range. The dots in the middle of each range control corresponds to the center knob positions in the player.

The keyword toggles allow you to specify whether songs being retrieved should, or should not, include the given keyword. The middle position is neutral. Four selection keywords can be active at any time. You can select which ones in the top panel library actions.

Standard retrieval is 2.5 stars (the default rating) or better. Toggle this setting to pull higher rated or include more depth. The default "Include Untagged" keyword filtering should work for most situations. Change this if you want to explicitely look for songs without any associated keywords, or for songs with at least one associated keyword.

By default, frequency filtering "Fq" is on. If you want to retrieve songs regardless of when they were last played, you can switch this off. Be aware songs might repeat weirdly. You can also completely switch off all filtering in the deck panel if you are having trouble searching.

The Deck Panel

The deck panel shows matching songs that are set to play next. If you change filter settings, what's on deck gets rebuilt. The search box matches all song text, even your comments. If you don't find what you are searching for, temporarily bypass all filtering using the filter toggle to the left of the search box.

To the right of search, there are three alternate display toggles: The info button gives details on how songs are being filtered. Album view switches to showing all songs on the album, regardless of filtering. In album view, songs play from one track to the next. The history view shows you what you've played so far in case you want to play something again.

Clicking a song on deck brings up its deck transport controls. You can play the song immediately, move it to the top of the deck, skip it, or snooze it (mark as tired and skip).

The Top Panel

The top panel provides account actions and library actions.

Account Actions

If you are running locally, the account actions link will say "Digger" until you have signed in. It is not required to connect the local server to DiggerHub, but connecting will sync your data and allow for collaborating with music fans.

A music fan is someone whose musical listening interests and reactions you respect and enjoy. You might not agree on everything, but you definitely agree on some things, and you might share tips and reactions to various songs and artists.

Library Actions

The library actions display shows general info about your music library (local files or web streaming). Use "Choose Keywords" to select which keywords to use for filtering and in what order they should be displayed. You can remove keywords you don't want to use anymore.

For streaming, the information display shows when your service library was last imported. If it's been a while, you can click that link to check the service again. For local files, click the "Read Files" button to re-read everything. If you have folders in your library that should be ignored, add them to your "Ignore Folders".

Default Keyword Descriptions

The default keywords have been chosen and tested over a period of years to provide positive and negative selection power in a wide variety of situations. The goal is to minimize the number of keywords in play while covering most common music playing situations.

You can synthesize "Party" from "Social", matching the Approachability and Energy Level as appropriate for the situation and perhaps switching on "Dance" later. Keywords like "Morning", "Workout", "Commute" etc have similarly fallen by the wayside. Genre categories get seriously tedious if there are too many, so go broad for maximum leverage.

Local Files Configuration

If you are running Digger locally on your computer, the Digger local server runs at http://localhost:6980 by default. You can configure this, and where to find your music files.

To change where Digger should read your music files from, open Library Actions in the top panel, then click either the "Music Files" or "Digger Data" links to restart Digger in config mode. In config mode, you can set where to find your music files, and/or put your Digger database file somewhere other than your home folder. Since browsers are not generally allowed to access your local file system, you'll have to modify the paths directly as text.

You can change other details of how Digger runs locally by modifying .digger_config.json in your home folder. If you ever need to reset Digger to its default settings, delete this file and Digger will recreate it from its default setup. The configuration settings are:

The "spawn" section contains contains information about the command to open a browser when Digger starts up. The subsections are organized based on the platform key as returned by node require("os").platform(); - e.g. "darwin" for MacOS. You can change the startup command that gets run if you understand the structure, for example to open a specific browser or run a script.

The "acctsinfo" contains your account information after you have signed in to DiggerHub from local Digger. It's best not to modify this part directly. Do not share your .digger_config.json with others since it has your email address and access token.

Accessing Your Data

If you are running Digger on your computer, all your song data is located in the file named by dbPath in your .digger_config.json file. By default this is digdat.json in your home user folder. On mobile devices, data is stored with the application files and is removed if you uninstall the app. To move your data from one device to another, sync it to the hub.

To report a breach of privacy obligations, or to permanently remove all your data from the server, contact support using the link on the website.

Digger Hub Sync

When you join DiggerHub, Digger synchronizes your local song data with data saved on the site. This is handy as a backup, and great if you also run Digger from the web or from another computer.

The initial synchronization process can sometimes take a while, depending on how much song data you have. Once the initial sync is done, it's usually very quick. You'll notice the "hub" indicator light displayed on the player panel while sync is ongoing. Clicking the indicator link will open the library actions where the "Hub Sync" line shows how many songs have been uploaded and downloaded. The status display shows "init", "processing", "scheduled", or (hopefully not) an error message. The "Reset" link can be used to restart hubsync if you suspect it might have hung up due to network issues or whatever.

For advanced tech details on how hub sync works, reference hubsyncNotes.txt in the same project folder as this manual.


When finding common songs between fans or music sources, DiggerHub matches on the song Title, Artist, and Album. These fields are created during library import, typically by reading the song metadata. If a field has a bad value, you can correct it in the tuning options on the player panel. When you correct a field, you override the library import values, you do not change the underlying music file.

If you choose to change the metadata in the source music file, using a music player interface or similar tool, Digger will read the new values next time you play the song.

The variety of inconsistencies in song metadata is a source of constant entertainment. For best results when overriding a field, use the common value and put anything else in parentheses. "My Song" and "My Song (remixed)" are considered different values within your collection, but equivalent between fans or across music sources.

For advanced tech details on metatdata matching, reference metadata.html in the same project folder as this manual.