DiscoDOS documentation

Quickstart Guide

Installation

Please head over to the INSTALLATION document for step by step instructions on how to get DiscoDOS running on your machine.

Importing your Discogs collection

To let DiscoDOS know about our Discogs record collection we have to import a subset of the available information to the local database (the so-called DiscoBASE).

disco import

Commands Chart

Before you move on with the Basic Usage Tutorial have a look at the following picture. It shows how disco - The DiscoDOS’ main command - is working. Usually a disco command is built from multiple words and options (-x, –something). The top half of the chart describes how the put those components together to create a working command. The bottom half shows some common usage examples.

Commands Chart

Basic Usage Tutorial

When importing is through, create a new mix:

disco mix my_mix -c

View your (empty) mix:

disco mix my_mix

Try adding one of your collection’s tracks to the “mix” you just created.

disco mix my_mix -a "Amon Tobin Killer Vanilla"

If DiscoDOS realizes you are offline it will search in the local database only. Only online search understands track names, offline search doesn’t, it needs artists and/or release names. Learn why, further below.

Be precise when asked for the track number on the record: A1 is not the same as A.

View your mix again, your track should be there. verbose view (-v) shows that track and artist names are still missing because DiscoDOS by default is minimalistic - the initial import command did not fetch this data yet:

disco mix my_mix -v

Add some more tracks!

Now get track artist/titles for all the tracks in the mix. If track numbers are not precise (eg A vs A1) data won’t be found!

disco mix my_mix -u

Use the verbose mode to see all the details pulled from Discogs:

disco mix my_mix -v

Ask what more you could do with your mix and its tracks (short option would be -h):

disco mix my_mix --help

Edit details of the third track in your mix:

disco mix my_mix -e 3

There is also a bulk-edit option to edit specific fields of all tracks in the mix. Read about it in the command reference section of The mix command

Get additional data about your mix’s tracks from MusicBrainz and AcousticBrainz (key, BPM, links):

disco mix my_mix -zz

Read more about the *Brainz update process here: The import command

Common Tasks

This section guides you through typical DiscoDOS workflows. If you would rather like to read an in-detail explanation of what each command does, go to the DiscoDOS User’s Manual.

What’s the quickest way to document a mix?

DiscoDOS can best help you when it’s feeded with as much of your DJ’ing habits as possible. Writing down a mix is done in a matter of minutes. Best you listen through a mix recording while having your records near you. Certainly a mix does not have to be a complete DJ set, it could just be some track combinations you like to play recently. Let’s get started by creating a new mix:

disco mix my_mix -c

The easiest command to remember for adding tracks to the mix is this one:

disco mix my_mix -a "artist title album"

If you hold the record in your hand and know exactly what track it is you played, the quickest way would be using the search subcommand, because the tracknumber on the record (A, B, A1, A2, etc.) can be given directly in the command. This spares you the question of which track on the record you’d like to add:

disco search "artist title album" -m my_mix -t A2

Note: Your search terms don’t have to include artist, title and album. Also label names and catalog numbers are valid.

While listening through an older recording it happens that you don’t remember what it was exactly you played. Just skip over an unknown track and move on with writing down the rest of the mix. When you’ve later figured out what it was you played, squeeze in tracks at the right position in the mix with:

disco search "artist title album" -m my_mix -t A2 -p 12

The -p option works in combination with the mix subcommands well:

disco mix my_mix -a "artist title album" -p 12

Note if you are new to command line tools: Make use of your shells command history and re-use and edit your commands. Usually this is done using cursor keys up and down.

More about the subcommands used in this guide is found here: mix command, search command.

I’m stuck in a mix

You’re in the process of compiling a mix for a gig. You just played this one tune that was really fitting well, but now you’re stuck and don’t know how to move on. You try out different records, nothing seems to work.

DiscoDOS can tell you in what combinations you ever played this tune in the past:

disco suggest "search terms to find the tune"

Another option would be to let it show you a pool of tracks sharing similiar key and BPM:

disco suggest -k Am -b 123

Note: If your tune(s) do not have key and BPM data yet, let them “match” with MusicBrainz first, by using the update from *Brainz search action

I’d like to quickly rate my transitions

You are listening to a recording of a mix you have already documented into DiscoDOS and now would like to quickly rate your transitions, so you and DiscoDOS can learn from it.

Use the bulk-edit function to change specific fields of your mix’s tracks:

disco mix "the mix name" -b trans_rating,trans_notes

Learn more about this function in the mix command section.

Note: Currently DiscoDOS rating analysis system is not finished. This will be coming in future version. As a preparations for this feature, you only are allowed to put these character combinations into the trans_rating field: ++, +, ~, -, –

I got a new record and want to quickly use it in DiscoDOS without re-importing everything

Search for the record on discogs.com. Get the ID from the release pages URL (eg. https://discogs.com/release/123456) and import it:

disco import 123456

Get artist/title for each track

disco search 123456 -u

Get key and BPM from MusicBrainz/AcousticBrainz:

disco search 123456 -zz

Note: Certainly you can always find a tune in your collection by using search terms. You don’t have to use the release ID. We use it here because we have it at hand already

A regular search command and starting *Brainz matching:

disco search "new release new tune" -zz

There is another convenient way when you are in the process of writing down a mix, and realize you can’t find the release because you didn’t add it to the collection yet: Use the -a option of the mix subcommand. Then, instead of searching for a text-term, we hand over a Discogs release ID. DiscoDOS will look for this exact release ID and add it to your Discogs collection as well as to the local DiscoBASE. As expected with the mix -a commmand, the interactively selected track will be added to your mix too:

disco mix fat_mix -a 123456

I’d like to get as much information about my music as possible - in one go!

As you’ve probably learned already, DiscoDOS doesn’t import all information about a record collection at once but rather “on user request”. Eg. single tracks or whole mixes can be asked to be filled in with additional data from Discogs or AcousticBrainz. When dealing with record collections containing hundreds or even thousands of records, obviously working through all of them via the APIs of online information services takes a lot of time, but certainly DiscoDOS can be asked to do it:

To make a full import of your whole record collection from Discogs (all releases INCLUDING all tracks on them) execute:

disco import --tracks

Note: This command can also be used for an initial import (you just started using DiscoDOS - DiscoBASE is still empty).

1000 records including a total of 3000 tracks complete in about 20 minutes

To get additional data from MusicBrainz and AcousticBrainz (key, BPM, weblinks to release- and recordingpages), execute:

disco import --zz

Note: This command requires the import-tracks command above, being completed already.

This process will take hours and hours, depending on the size of your collection

Read more on “*Brainz matching and importing” and it’s performance in the the import command chapter. You will also learn how the process could be resumed if for some reason the computer had to be switched off or the connection broke away.

Here’s a trick to execute both commands one after the other. We use the “command concatination” features of our shell:

On Windows, do:

disco import --tracks  &  disco import -zz

on macOS or Linux it’s:

disco import --tracks  &&  disco import -zz

Leave this running “overnight” - You will see a final summary after each of the commands completes, telling you the exact time it was running and how much information was processed and imported. If you’d like to help improve this manual, copy/paste your stats into a Github issue, it would help me a lot to state more accurate estimates here.

I’d like to use my DiscoBASE on multiple computers

DiscoDOS includes a built-in backup and restore feature that can also be used to sync a DiscoBASE between multiple computers.

We need a place to store our discobase.db file online. Currently there are two options:

  • Dropbox

  • A folder on a webserver

This section will describe how to use Dropbox only, find the webserver option documented here: FIXME

To allow DiscoDOS access to your Dropbox account you need an access token. To obtain it follow the steps in chapter Configure Dropbox Access for discosync, then come back here.

To backup your DiscoBASE, execute:

discosync --backup or in short discosync -b

To restore it on another computer, execute:

discosync --restore or in short discosync -r

Note: Certainly you can use this feature to backup and restore your DiscoBASE on one computer only. The commands are the same

User’s Manual

Even more details on what DiscoDOS can do is found in the User’s Manual. This quickstart guide should have given you a first impression on how things work, now consult the User’s Manual for advanced usage concepts. You will also find some background info on how things work and why.

Installation Guide

There are two ways of installing DiscoDOS:

  • Released version (get a program that just works, is easy to install and well tested)

  • Development version (get the latest features, contribute to DiscoDOS by trying out new things and reporting back what you think. There is a separate document about installing the development version.

Install released version

Windows

Download the latest Windows installer (DiscoDOS_version.exe) from the release page and run it.

Click Start Menu - DiscoDOS - DiscoDOS

A new command prompt window opens and the DiscoDOS main command disco runs automatically.

On first launch, disco will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter Configure Discogs API access, then come back here!

Now that you’ve put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).

Note: In case you are updating from a previous DiscoDOS version, your data will be kept and your database’s schema might be upgraded automatically

If the connection to Discogs is working, setup asks you to view a little tutorial teaching you how it works - hit enter and follow the steps.

Your starting point for further documentation is the Quickstart Guide. Your next logical step is importing your Discogs collection.

Note: The disco and discosync commands are installed globally, you can use the Start Menu entry to run them but they also work in any cmd.exe window.

Note: DiscoDOS generates the following files which are kept in C:\Users\your_name\Documents\discodos\ (path may vary depending on your OS-language):

  • The DiscoDOS configuration file (config.yaml)

  • The DiscoBASE (discobase.db)

  • A logfile (debug.log)

Improve Command Line Experience on Windows

I would highly recommend installing “Microsoft Windows Terminal”. It will provide a much nicer command line experience than cmd.exe! It has a better looking font out of the box, better command auto completion and overall is the command line application Windows was missing for ages (IMHO). Future DiscoDOS versions will use Windows Terminal in the Start Menu launchers by default.

Get “Microsoft Windows Terminal”

  • from the Microsoft App store (you’ll find it in your Start Menu and you need a Microsoft account)

    • get a stable release version

  • or from the Microsoft github page: https://github.com/microsoft/terminal/releases

    • get a stable release version

    • or one of the preview version (I’d recommend them, they are usually stable enough!)

Some features worth trying out

  • Zoom in/out (resize terminal text) using “ctrl + mouse wheel” (e.g handy when showing mixes in verbose view (disco mix mix_name -v)

    • Alternatively zoom in/out using “ctrl +/ctrl -“

  • Paste text from clipboard using “right/secondary mouse button”

  • Command completion using “tab key” (cmd.exe had this already, yes - anyway it feels a little better here IMHO)

  • Open a new terminal windows using “ctrl - shift - n”

  • Open a new terminal tab using “ctrl - shift - t”

macOS

Download the latest macOS package (DiscoDOS_version.dmg) from the release page

Doubleclick the .dmg file - Drag and drop DiscoDOS.app to Applications folder.

Launch DiscoDOS.app

A new Terminal window opens and the DiscoDOS main command disco runs automatically.

On first launch, disco will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter Configure Discogs API access, then come back here!

Now that you’ve put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).

Note: In case you are updating from a previous DiscoDOS version, your data will be kept and your database’s schema might be upgraded automatically

If the connection to Discogs is working, setup asks you to view a little tutorial teaching you how it works - hit enter and follow the steps.

Your starting point for further documentation is the Quickstart Guuide. Your next logical step is importing your Discogs collection.

Note: The disco and discosync commands are now installed globally, you can launch DiscoDOS.app to open a Terminal but they also work in any other Terminal window.

Note: DiscoDOS generates the following files which are kept in /Users/your_name/Documents/DiscoDOS/:

  • The DiscoDOS configuration file (config.yaml)

  • The DiscoBASE (discobase.db)

  • A logfile (debug.log)

Linux

Most Linux distributions come with a compatible Python3 version in there package repositories already. Please refer to the contribution manual on how to install the DiscoDOS Python package.

If you use Debian GNU/Linux or any distribution that is based on it: DiscoDOS v1.0_rc2 is available in Debian unstable. It is also available in the current Ubuntu release as well as in Ubuntu Studio, Linux Mint and other Ubuntu-based distros. Just apt install discodos and you are good to go. If you’d like to use the latest version of DiscoDOS please be patient or even better: Install DiscoDOS as a Python package. Learn how by following above link to the contribution manual.

Configure Discogs API access

To access your Discogs collection you need to generate an API login token and put it into the configuration file.

  • Login to discogs.com

  • Click your avatar (top right)

  • Select Settings

  • Switch to section Developers

  • Click Generate new token

  • Run disco - you’ll be prompted to put in the token.

Note: If you are updating from a previous DiscoDOS version, your config.yaml is existing and has a token set up already, thus you won’t be bothered!

Edit configuration file manually

Alternatively you can open the configuration file with a texteditor and copy/paste the generated Discogs token into it by hand:

  • Windows: Edit MyDocuments/discodos/config.yaml (use Start Menu entry “DiscoDOS/Edit Configuration File”)

  • macOS: Edit /Users/your_name/Documents/config.yaml (secondary click (two fingers) - “Open With” - “TextEdit.app”).

  • Linux: Edit $HOME/.discodos/config.yaml

The line in config.yaml should look something like this then:

discogs_token: XDsktuOMNkOPxvNjerzCbvJIFhaWYwmdGPwnaySH

Configure discosync - The DiscoDOS backup & sync tool

discosync works with timestamps (local modification time) of the database file. It will never backup a file that has been already backuped up. Even if the file has been shared to another computer, it will only be overwritten if its contents was changed. This is to reduce the amount of (useless) backup files in your dropbox account or on your webserver.

The format of files always is “database_name_YYYY-MM-DD_HHMMSS.db”

Configure Dropbox Access for discosync

To prepare your Dropbox account and DiscoDOS configuration, do the following:

  • We need to create a new “Dropbbox App” in your account: https://www.dropbox.com/developers/apps/create

  • Step 1: “Choose an API” - select “Dropbox API”

  • Step 2: “Choose the type of access you need” - select “App folder”

  • Step 3: “Name your app” - enter “discodos”

  • Click “Create app”

  • Scroll down to section “OAuth 2” - Click the “Generate” button right below “Generated access token”

  • Double click and copy the token to the clipboard

  • Put the token into the config.yaml file on all the computers you would like to use this DiscoBASE.

    • open with TextEdit.app on Mac

    • open with Notepad on Windows.

The line in config.yaml should then look something like this (watch out for the surrounding quotes):

dropbox_token: 'abcxyzabcxyzabcxyzabcxyzabcxyzabcxyzabcxyz'

If you want to delete your Dropbox app again or generate a new token because you lost it, go to the Dropbox app console.

Certainly you can also access the backup files via the Dropbox webinterface - Click the “discodos” app on the home screen - you will find a subfolder “discodos” containing all your backed up DiscoBASE files.

Configure a webserver folder for discosync

If you don’t like saving your stuff to Dropbox and happen to have your own personal webspace somewhere, discosync can use it to save backups. The folder needs to have these features enabled:

Even though it is not mandatory, the following is highly recommended to securly transport your password over the wire:

  • Webserver running SSL (https://…)

Configuration steps may vary, if you can’t do above configurations in your webhosters “configuration console” try contacting their support.

If you have (root) access to your server and it’s an Apache webserver, configuration of a suitable folder looks like this:

   <Directory /var/www/discodos/>
      AllowOverride None
      DAV On
      AuthType "Basic"
      AuthName "Restricted Area"
      AuthBasicProvider file
      AuthUserFile "/etc/apache2/.htaccess_discodos"
      Require user my_discosync_user
   </Directory>

To create the password file:

htpasswd -c /etc/apache2/.htaccess_discodos my_discosync_user

Test if accessing your backup space is working with your webbrowser: https://www.yourdomain.com/discodos/. Usually a popup asks you for your credentials.

If everything’s fine adjust your DiscoDOS configuration file (config.yaml)

webdav_user: 'my_discosync_user'
webdav_password: 'secret123'
webdav_url: 'https://www.yourdomain.com/discodos/'

Go to the discosync chapter in the User’s manual

User’s Manual

This document contains in-detail explanations about everything you can do with DiscoDOS. If you’d like to see how to do typical day to day tasks, jump to the Common Tasks section on the README page, and come back here later.

General things about command line tools

In case you don’t use command line tools much: disco is designed as such and thus each option has a short form and a long form. For example the help output of the disco main command can be written two ways:

disco --help or disco -h

another example:

disco suggest --bpm 123 is the same as disco suggest -b 123

Throughout this section, mostly the short forms are used, but sometimes the long forms too because they’re just more self-explanatory.

Also a common concept with command line tools is that “optional arguments” (the ones starting with a dash) can be put before or after “positional arguments (in this case the mix_name):

disco mix new_mix -c is the same as disco mix -c new_mix

Also the order of “optional arguments” is freely choosable most of the time:

disco search "search terms" -m new_mix -t A2

is the same as

disco search "search terms" -t A2 -m new_mix

disco - the main command

DiscoDOS’ main command is disco, to view it’s help:

disco -h

It contains four subcommands, namely: mix , suggest, import, search

To execute a subcommand you would eg type:

disco search ...

Each subcommand has its own built-in help output:

disco mix -h
disco suggest -h
disco import -h
disco search -h

disco - global switches

The general behaviour of disco can be altered by some “optional arguments”:

Enable INFO logging output or DEBUG logging output on your terminal (usually only relevant if you’re investigating errors, are a developer or just want to know what DiscoDOS is doing under the hood):

enable INFO logging (-v) or DEBUG logging (-vv) output:

disco -v ... or disco -vv ...

DiscoDOS checks if it’s online automatically but can be forced to stay in offline mode:

disco -o ...

The disco subcommands

Each subcommand has its typical purpose but some actions can be executed from within other subcommands as well.

This chart gives some examples of what each subcommand can do:

Commands Chart

The mix command

A mix is basically just a list of tracks in a specific order, a playlist, a track pool, you name it.

Create a mix. You will be asked to put in general info about the mix (venue, last played date). Make sure the played date is in the format YYYY-MM-DD:

disco mix my_mix -c

Delete a mix (yes, it’s a capital D):

disco mix my_mix -D

Copy a mix. You will be asked for the name of the copy. (Note: –copy doesn’t have a short form option):

disco mix my_mix --copy

Edit general mix info (venue, played date):

disco mix my_mix -E

Add a track to a mix. You will be asked for the track number on the found release. Note: Tracks can be added using the search command as well:

disco mix my_mix -a "search terms"

To add the track at a specific position in the mix, rather than at the end:

disco mix my_mix -a "search terms" -p 3

Edit details or 3rd track in the mix (key, key_notes, BPM, transition rating, transition notes, track notes, position in the mix, track number on the record, custom MusicBrainz recording ID):

disco mix my_mix -e 3

Delete 3rd track in the mix:

disco mix my_mix -d 3

Bulk-edit selected fields of all tracks in a mix. You can cancel editing without data loss by pressing ctrl-c. Data is saved after each track.

disco mix my_mix -b trans_rating,bpm,key

Available field names: key,bpm,track_no,track_pos,key_notes,trans_rating,trans_notes,notes,m_rec_id_override (Make sure your field list has only commas and no spaces in between!)

To start bulk-editing at a specific track position rather than at track 1:

disco mix my_mix -b trans_rating,bpm,key -p 3

Get track names for whole mix from Discogs:

disco mix my_mix -u

Start getting track names at position 3 in the mix, rather than at track 1:

disco mix my_mix -u -p 3

Get additional track info for whole mix from MusicBrainz/AcousticBrainz (key, bpm, links):

disco mix my_mix -z

Start getting MusicBrainz/AcousticBrainz info at position 3 in the mix, rather than at track 1:

disco mix my_mix -z -p 3

Run a “detailed *Brainz match” (more likely to find matches but significantly slower)

disco mix my_mix -zz

Get track names for all tracks in all mixes from Discogs:

disco mix -u

Get MusicBrainz/AcousticBrainz info for all tracks in all mixes from Discogs. Do a “detailed *Brainz match” run:

disco mix -zz

*Brainz matching is a tedious process for DiscoDOS (more details on this here), if you have to switch off your computer for any reason while it’s running, cancel the process using ctrl-c and it later at the given position (in this example track number 150 in the list of all tracks in all mixes):

disco mix -zz --resume 150

The suggest command

The suggest command helps a DJ find possible track combinations by reporting how a track has been used in the past or by finding tracks fitting with certain criteria. Fun fact: These features were the initial ideas for writing a program like DiscoDOS.

Find out in which combinations a track ever was played by looking through all your mixes. This command does a regular search in the collection, spits out a “first match” release and asks for a track number on the release. The presented output shows “snippets” of mixes, telling you exactly which tracks you have used before and after the selected track:

disco suggest "amon tobin kitchen sink"

Show all tracks in collection containing “Dm” (D minor) either in the user-key or AcousticBrainz keys fields (key, chords_key).

disco suggest -k Dm

DiscoDOS allows a user to put in more than one key in the user-key field. Information like “Am/Dm/Gm” is allowed. To find this information the following search could be used. Note the wildcard character being the percent sign (%):

disco suggest -k "Am%Gm"

Certainly the a record with “Am/Dm/Gm” in the user-key field would also be found by a simple search like this:

disco suggest -k Am

Find all tracks in collection with a BPM around 120. The pitchrange of a typical turntable is taken into account. Currently this is hardcoded to +/-6 percent (this will be a user-configurable value in future DiscoDOS versions):

disco suggest -b 120

key and BPM search can be combined:

disco suggest -k Dm -b 120

Note: The key and BPM suggest commands require sufficient information in the DiscoBASE. Either in the user-editable key and BPM fields or in the AcousticBrainz fields

Read how to automatically fill these fields with data from AcousticBrainz in the following section about the import command.

The import command

You can update your DiscoBASE from your Discogs collection at any time, if data is already existing, it will be updated. Due to the Discogs API being not the fastest, it takes some time though. There are other ways for adding single releases to Discogs AND to your DiscoBASE simultaneously.

Note: This imports all your releases, but not the tracks on them

disco import

A quicker alternative, if you are about to import just a couple of new releases is to use the -a option. The release will be added to your Discogs collection and also imported to DiscoBASE. To get the Discogs release ID, just head over to discogs.com, search for the release. You will find the release ID in the URL of the release (eg https://www.discogs.com/release/123456).

Note: You don’t have to click “Add to Collection” on discogs.com, DiscoDOS does this for you

disco import -a 123456

To add a release to DiscoBASE only (because it’s been already added to your collection via the Discogs web interface), just use the import command with a release ID attached. (Note: Unfortunately this way it takes significantly longer because of drawbacks in how the collection data is accessible via the API):

disco import 123456

To import all releases including all tracks in your collection use the –tracks option (can be replaced by its short form -u). 1000 records take about 20-30 minutes to import:

disco import --tracks

To add additional data to your tracks from MusicBrainz/AcousticBrainz (key, BPM, links) use the -z option. Your releases will then be “matched” one-by-one with MusicBrainz - this is not the easiest task for DiscoDOS, several things have to be “tried” to get it right. Differences in spelling/wording of catalog number, artists, title, track numbers, track names in MusicBrainz compared to Discogs are the main reason why it takes that long:

Note: This process will take hours. Best you let it run “overnight”

disco import -z

An even more detailed “matching” is done by “doubling the -z option”. It takes significantly longer and you will get more results but still: Don’t expect to find a match for all of your releases. Please take a minute and report back how the matching went by opening a github issue:

disco import -zz

Also remember that it’s unlikely that MusicBrainz even has an entry for each of your records. Discogs still is the most complete music database on earth compared to others. Most definitely when it comes to Vinyl records.

Also note that often it happens that a MusicBrainz track can be “matched” but AcousticBrainz does not have an entry for it yet.

If for some reason you can’t complete the run (connection problems, having to switch of your computer, …) you can resume the process at a later time. DiscoDOS spits out regularly how many tracks have been matched already and how many are to be done. This will resume the matching at track number 2500 in your collection:

disco import -zz --resume 2500

The “*Brainz match process” currently adds the following data to releases:

  • Release MusicBrainz ID (Release MBID)

  • weblink to the MusicBrainz release

and the following data to tracks:

  • BPM

  • key

  • chords key

  • Recording MusicBrainz ID (Recording MBID)

  • weblink to the MusicBrainz recording (A track is called a recording in “MusicBrainz speak”)

  • weblink to the AcousticBrainz recording (AcousticBrainz uses the same recording MBID as MusicBrainz - this is the link between the two services!)

The search command

As the name implies, this command searches in your collection. By default it uses the Discogs API to search for release names, track names, track artists, catalog numbers and labels.

To search an album of artist “Amon Tobin” you would type:

disco search "Amon Tobin Foley Room"

You will see the Album’s details and its contents.

Note: The online search is designed “first match”

So this gives you the first found “Amon Tobin” album in your collection only. You have to be more specific to find a particular album:

disco search "Amon Tobin"

If you currently are not connected to the internet or you enable “offline mode” the search command behaves differently: Your search terms are only applied against the release title and the release artist(s), but not the track name. There is a reason for this: DiscoDOS by default does not import track name. Even though certainly you have the option to import track names, the search does not rely on this. Maybe this behaviour changes in future releases. It was a design decision in the first DiscoDOS prototype versions.

Note: The offline search shows a “list of matching items”

search command actions

To “do” something with a track on an album you need to append an “optional argument” to the command. The following actions can be applied to the found track:

  • “edit track” (option -e)

  • “add track to mix” (option -m)

  • “update from Discogs” (option -u)

  • “update from *Brainz” (option -z)

search action “edit track”

To edit the track’s details in the DiscoBASE you use:

disco search "Amon Tobin Foley Room" -e

You will see the album’s contents and be asked to put in a track number (eg A1, C2, …). Then you will be walked through all the “editable” fields. It’s pretty self-explanatory, but read the hints on the screen.

If you know which track number you’d like to edit already, provide it on the command line directly. You won’t be asked for the track number then:

disco search "Amon Tobin Foley Room" -e -t B2

search action “add track to mix”

The track you select on the found release will be added to the given mix-name:

disco search "Amon Tobin Foley Room" -m my_mix

If your mix’s name contains spaces, wrap it in double quotes:

disco search "Amon Tobin Foley Room" -m "my longish mix name"

As a shortcut you can always just use the mix’s ID number (you see the numbers in the output of the disco mix command):

disco search "Amon Tobin Foley Room" -m 27

Certainly also here you can provide the track number on the command line already. So to add track A2 on “Foley Room” to mix number 27:

disco search "Amon Tobin Foley Room" -m 27 -t A2

search action “update from discogs”

As already mentioned already, DiscoDOS is minimalistic by default. The default import command disco import just gets exactly this data from Discogs: release IDs, release titles, release artists, catalog numbers. To put track names of a particular track into the DiscoBASE as well you’d use:

disco search "Amon Tobin Foley Room" -u

Again, combination with -t is possible:

disco search "Amon Tobin Foley Room" -u t A2

To make all track names on all releases in your collection available offline, use:

disco search all -u

Note: This is exactly the same as using disco import --tracks or in short: disco import -u.

Read more on importing release and track information in the import command section

search action “update from *Brainz”

To extend a tracks information with data from MusicBrainz and AcousticBrainz:

Note: To make this work, the track must have been updated from Discogs with track names already. See update from Discogs action above.

disco search "Amon Tobin Foley Room" -z

If the track couldn’t be matched with the regular match command, try the “detailed match” command (takes more time, but chances on finding a match are higher):

disco search "Amon Tobin Foley Room" -zz

or as usual with track name already in the command:

disco search "Amon Tobin Foley Room" -zz -t A2

If you’ve already imported all your track’s names to the DiscoBASE, you could even try to update all tracks with MusicBrainz information (takes a couple of hours):

disco search all -z
disco search all -zz

Read more on the performance of the *Brainz match process and what exactely it imports in the import command section

discosync - The DiscoDOS backup & sync tool

discosync is used to save the DiscoBASE to the cloud and restore it if something went wrong. It also can be used to share it between multiple computers. There are currently two options, for storing the backups:

  • Dropbbox

  • A folder on a webserver

A little configuration hast to be done. Follow the steps in the Dropbox configuration chapter or the Webserver configuration chapter

Depending of your chosen way of saving backups you have to launch discosync differently; Option -t selects which type of storage should be accessed:

discosync -t dropbox ...
discosync -t webdav ...

The “types” can be abbreviated:

discosync -t d ...
discosync -t w ...

Backup

The backup command is straight forward and does not require any user-interaction after launching:

To backup to your Dropbox:

discosync -t d --backup

or use its short form: discosync -t d -b

Dropbox currently is the hardcoded default “storage type”, so actually it’s sufficient to run:

discosync -b

Note: The default backup storage type might be configurable in future DiscoDOS releases

To backup to a WebDAV folder:

discosync -t w --backup

short form: discosync -t w -b

Viewing existing backups

Dropbox:

discosync --show

or short: discosync -s

WebDAV:

discosync -t w --show

or: discosync -t w -s

Restore

Restoring your database from a backup is an interactive process - you will be asked which backup you’d like to restore and warned that your local discobase.db file would be overwritten.

Dropbox:

discosync --restore

or short: discosync -r

WebDAV:

discosync -t w --restore

or short: discosync -t w -r

Contribution

Install development version

If you’d like to contribute to DiscoDOS development or just want the most “bleeding edge” version, you’ll most likely want to install it tracking this repos master branch or your fork’s feature branch. Follow the guides in this document to achieve that.

I usually try to keep things stable in the master branch. I use it myself on my production database, so it just has to work. Seldomely there will be major bugs that could corrupt your data. In any case make sure you use DiscoDOS’ neet built-in backup/sync feature!).

DiscoDOS is written entirely in Python. The majority of time, it was coded on a MacOS X 10.13 machine with Python installed via homebrew, thus it’s tested well on this platform. There are some users happily using it on Winodws 10 already. I myself develop and use it on Linux machines too, and it seems to work as good as on my Mac.

Basically it will run on any OS as long as the following prerequisites are met. Please report back in any case, wether it’s working fine or you find things that seem unusual on your OS. Thanks a lot!

Prerequisites

You need to have these software packages installed

  • git

  • Python version 3.6 or higher

Getting them differs according to your OS

  • Most Linux distributions have git and Python available within their package repositories.

  • On Windows download from here: https://git-scm.com/download, https://www.python.org/downloads

  • On MacOS I suggest getting both packages via homebrew: https://brew.sh/ (If homebrew seems overkill to you, just use the Windows links above)

Make sure git and python can be executed from everywhere (adjust your PATH environment variable accordingly).

During the Python setup on Windows choose “Customize installation” and select the following options:

  • pip

  • py launcher

  • Associate files with Python (requires the py launcher)

  • Add Python to environment variables

Windows - Install into virtual environment

Skip this chapter if you are on macOS or Linux!

Please use the regular command prompt window (cmd.exe) and not the “git bash”, otherwise the statements using the %HOMEPATH% environment variable won’t work! Also note that Windows paths can be written with slashes instead of the usual backslashes these days (putting them inside of quotes is mandatory though!) - in the very unlikely case your Windows version doesn’t support this, please just change the paths to use backslashes.

Jump to your homedirectory, clone the repo and change into the cloned repo directory.

cd %HOMEPATH%
git clone https://github.com/JOJ0/discodos.git
cd discodos

Create and activate a virtual Python environment!

python -m venv "%HOMEPATH%/python-envs/discodos"
"%HOMEPATH%/python-envs/discodos/Scripts/activate.bat"

Double check if your environment is active and you are using the pip binary installed inside your %HOMEPATH%/python-envs/discodos directory.

pip --version

You should see something like this:

pip 19.2.3 from c:\users\user\python-envs\discodos\lib\site-packages\pip (python 3.8)

Install the necessary dependencies into your environment:

python3 setup.py develop

Launch DiscoDOS’ main command and follow the steps shown:

disco

Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:

"%HOMEPATH%/python-envs/discodos/Scripts/activate.bat"

macOS or Linux - Install into virtual environment

Jump to your homedirectory, clone the repo and change into the cloned repo directory.

cd
git clone https://github.com/JOJ0/discodos.git
cd discodos

Create and activate a virtual Python environment! The environment will be saved inside a hidden subfolder of your homedirectory called .venvs/

python3 -m venv ~/.venvs/discodos
source ~/.venvs/discodos/bin/activate

Double check if your environment is active and you are using the pip binary installed inside your ~/.venvs/discodos/ directory.

pip --version

You should see something like this:

pip 18.1 from /Users/jojo/.venvs/discodos/lib/python3.7/site-packages/pip (python 3.7)

Install the necessary dependencies into your virtual environment:

python3 setup.py develop

Some command wrappers should have been installed too. Verify if they exist inside your ~/.venvs/discodos/bin directory:

which disco
which discosync

Launch DiscoDOS’ main command and follow the steps shown:

disco

Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:

source ~/.venvs/discodos/bin/activate

macOS or Linux - Install system-wide

This chapter describes how to install the DiscoDOS package into your global Python environment which is better suitable for just using it, rather than contributing/developing.

Install Python 3. On Debian based distros (Ubuntu, Linux Mint, …), do something like this:

apt install python3

on RedHat based (Fedora, CentOS, …):

yum install python3

Download the latest source package (DiscoDOS_version.tar.gz) from the release page

or clone the latest development version from github:

cd
git clone https://github.com/JOJ0/discodos.git
cd discodos

Install DiscoDOS into your global Python environment:

python3 setup.py install

Some command wrappers should have been installed. Verify if they exist:

which disco
which discosync

Launch DiscoDOS’ main command:

disco

On first launch, disco will create a configuration file for you. To access your Discogs collection, an access token has to be generated and put into the file. Follow the steps in chapter Configure Discogs API access, then come back here!

Now that you’ve put the token into the configuration file, DiscoDOS completes setup by creating a local database (the DiscoBASE).

Note: In case you are updating from a previous DiscoDOS version, your data will be kept and your database’s schema might be upgraded automatically

If the connection to Discogs is working, setup asks you to view a little tutorial teaching you how it works - hit enter and follow the steps.

Your starting point for further documentation is the Quickstart Guide. Your next logical step is importing your Discogs collection.

Note: The disco and discosync commands are now installed globally and will work in any terminal emulator.

Note: DiscoDOS generates the following files which are kept in ~/.discodos/:

  • The DiscoDOS configuration file (config.yaml)

  • The DiscoBASE (discobase.db)

  • A logfile (debug.log)

Video Tutorials

If you don’t like reading through longish documentation pages just head over to Youtube and learn how to do some basic DiscoDOS tasks:

Commands Reference

disco

the DiscoDOS CLI.

usage: disco [-h] [-v] [-o] {search,mix,suggest,import,setup} ...

optional arguments

-h, --help

show this help message and exit

-v, --verbose

increases output verbosity / shows what DiscoDOS is doing under the hood (-v is INFO level, -vv is DEBUG level).

-o, --offline

DiscoDOS checks for connectivity to online services (Discogs, MusicBrainz, AcousticBrainz) itself. This option forces offline mode. A lot of options work in on- and offline mode. Some behave differently, depending on connection state.

disco import

usage: disco import [-h] [--add-to-collection | --tracks | --brainz]
                    [--resume OFFSET]
                    [RELEASE_ID]
release_id

the Discogs release ID you want to import to DiscoBASE. If left empty, the whole collection will be imported. If the additional option -a is used, the release will be added to your Discogs collection _and_ imported to DiscoBASE. Note that a regular import of a given release ID is quite time consuming: We have to check wether or not this release ID is already in the Discogs collection (we don’t want duplicates), thus we have to run through all of your releases via the Discogs API. Unfortunately Discogs does not allow us to search for release IDs in ones collection, we only can “iterate” through them. Therefore the recommended way of adding newly gained releases is by using the -a option.

-h, --help

show this help message and exit

--add-to-collection, -a

This is the recommended (and fastest) way of adding newly gained releases to your collection. The given release ID is added to your Discogs collection (same as when you click an “Add to collection” in the Discogs Webinterface. Additionally the release is added to the DiscoBASE. Note that for performance’s sake, we don’t do a time-consuming check if the release is already in your Discogs collection by asking the Discogs API, but only do a quick check if the ID is in the local DiscoBASE already.

--tracks, -u

extends the Discogs import (releases and also tracks will be downloaded) - takes siginficantly longer than the regular import. Note: This is the same as “disco search all -u”.

--brainz, -z

imports additional information from MusicBrainz/AcousticBrainz. This action takes a long time. -z quick match, -zz detailed match (takes even longer, but more results). Notes: This is the same as “disco search all -z”. Prior to using this option, an extended Discogs import is recommended (disco import –tracks). Otherwise only tracks that were already downloaded to the DiscoBASE (eg used in mixes and updated using “disco mix -u”) will be updated.

--resume <offset>

resumes long-running processes at the given offset position (expects a number). You can combine this option currently with the *Brainz matching import operation only (-z, -zz)

disco mix

usage: disco mix [-h] [-v]
                 [-c | -D | -e POSITION | -E | -b FIELDS | -a SEARCH_TERMS | -r POSITION | -d POSITION | --copy | -u | -z]
                 [-p POSITION] [--resume OFFSET] [-s COLUMN]
                 [mix_name]
mix_name

mix name or mix ID being displayed, edited, created, copied, deleted, etc. If mix_name is left out, a list of available mixes is shown and all other arguments are ignored.

-h, --help

show this help message and exit

-v, --verbose

increases mix tracklist view detail. -v adds tracknames, artists, transition rating/notes and general track notes. -vv shows when and how MusicBrainz matching was done and also direct weblinks to Discogs releases, MusicBrainz releases/recordings and AccousticBrainz recordings.

-c, --create-mix

creates new mix (named as given in mix_name argument).

-D, --delete-mix

deletes the mix (given in mix_name) and all its contained tracks!

-e <position>, --edit <position>

edits/adds details of a track in a mix (editable fields: key, BPM, track number, position in mix, key notes, transition rating, transition notes, general track notes, custom MusicBrainz recording ID).

-E, --edit-mix

edits/adds general info about a mix (name, played date, venue).

-b <fields>, --bulk-edit <fields>

bulk-edits specific fields of each track in mix. Syntax of FIELDS argument: <field1>,<field2>,… available fields: key,bpm,track_no,track_pos,key_notes,trans_rating, trans_notes,notes,m_rec_id_override.

-a <search_terms>, --add-to-mix <search_terms>

searches for release/track in collection and adds it to the mix, This option is actually a shortcut to “disco search -m mix_name search_term” and behaves identically. If SEARCH_TERMS is a number, it is assumed being a Discogs release ID. A quick database check is done and if non-existent yet, the release is 1) added to the Discogs collection and 2) imported to DiscoBASE. This is a convenience function eg when trying to quickly add a release to the mix that’s not in the DiscoBASE yet (possibly an only recently gained record?).

-r <position>, --reorder-tracks <position>

reorders tracks in current mix, starting at POSITION. Note that this is a troubleshooting function and usually shouldn’t be necessary to use.

-d <position>, --delete-track <position>

removes the track at the given position from the mix.

--copy

copies the mix given in mix_name argument. Asks for new name!

-u, --discogs-update

updates tracks in current mix with additional info from Discogs. Can be combined with -p when mix ID provided or with –resume when mix ID not provided (all tracks in mixes update).

-z, --brainz-update

updates tracks in current mix with additional info from MusicBrainz and AcousticBrainz. Leave out mix ID to update every track contained in any mix. -z quick match, -zz detailed match (takes longer, but more results). Can be combined with -p when mix ID provided or with –resume when mix ID not provided (all tracks in mixes *Brainz matching).

-p <position>, --pos <position>

in combination with -a this option adds the found release/track at the given position in the mix (rather than at the end). In combination with -u, -z or -zz the update process is started at the given position in the mix.

--resume <offset>

resumes long-running processes at the given offset position (expects a number). You can combine this option currently with “all tracks in mixes Discogs update” (disco mix -u) or with “all tracks in mixes *Brainz matching” (disco mix -z, disco mix -zz).

-s <column>, --sort <column>

sort tracklist by specified column. add “asc” or “desc” to specify ascending or descending sort order. “track_pos asc” is the default. Experimental feature: currently expects sql column names.

disco setup

usage: disco setup [-h] [--force]
-h, --help

show this help message and exit

--force

force upgrade database schema - only use if you know what you are doing.

disco suggest

usage: disco suggest [-h] [-b BPM] [-k KEY] [search_terms]
search_terms

track or release name you want to show a “track-combination report” for.

-h, --help

show this help message and exit

-b <bpm>, --bpm <bpm>

suggests tracks based on BPM value, within a pitch-range of +/-6 percent.

-k <key>, --key <key>

suggests tracks based on musical key.

discosync

the DiscoDOS backup & sync tool.

usage: discosync [-h] [-v] [-t {dropbox,webdav,d,w}] [-b | -r | -s]

optional arguments

-h, --help

show this help message and exit

-v, --verbose

increase log verbosity (-v -> INFO level, -vv DEBUG level)

-t {dropbox,webdav,d,w}, --type {dropbox,webdav,d,w}

select synchronisation type: dropbox (default) or webdav (can be abbreviated: d or w)

-b, --backup
-r, --restore
-s, --show