From 981ebdfb77e8221913d7818324f9ba2966758593 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 23 Jul 2024 11:56:43 +0200 Subject: [PATCH 1/3] Replace disco with dsc (wholeword) in docs using vscode search/replace. --- sphinx/source/CONTRIBUTION.md | 16 +-- sphinx/source/INSTALLATION.md | 16 +-- sphinx/source/MANUAL.md | 144 ++++++++++----------- sphinx/source/QUICKSTART.md | 56 ++++---- sphinx/source/{disco.rst => dsc.rst} | 2 +- sphinx/source/index_commands_reference.rst | 2 +- 6 files changed, 118 insertions(+), 118 deletions(-) rename sphinx/source/{disco.rst => dsc.rst} (82%) diff --git a/sphinx/source/CONTRIBUTION.md b/sphinx/source/CONTRIBUTION.md index 401b360..3448cbb 100644 --- a/sphinx/source/CONTRIBUTION.md +++ b/sphinx/source/CONTRIBUTION.md @@ -77,7 +77,7 @@ Install the necessary dependencies into your environment: Launch DiscoDOS' main command and follow the steps shown: -`disco` +`dsc` _**Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:**_ @@ -116,13 +116,13 @@ Install the necessary dependencies into your virtual environment: Some command wrappers should have been installed too. Verify if they exist inside your `~/.venvs/discodos/bin` directory: ``` -which disco +which dsc which discosync ``` Launch DiscoDOS' main command and follow the steps shown: -`disco` +`dsc` _**Note: Make sure you always first activate your virtual environment when coming back to developing or using DiscoDOS:**_ @@ -158,19 +158,19 @@ Install DiscoDOS into your user's Python environment: Some command wrappers should have been installed. Verify if they exist: ``` -which disco +which dsc which discosync ``` If `which` didn't find those commands, make sure your $PATH environment variable contains the path the wrappers where installed to. Usually this is `~/.local/bin/` -_Note: On Debian-based systems there might be a file `/usr/bin/disco` on your system already provided by package mono-devel, thus depending on the order of paths in `$PATH`, `/usr/bin/disco` might be found before the DiscoDOS wrapper. Change `$PATH` to first search in `~/.local/bin` (export it in `.zshrc`, `.bashrc` or whatever shell you are using)_ +_Note: On Debian-based systems there might be a file `/usr/bin/dsc` on your system already provided by package mono-devel, thus depending on the order of paths in `$PATH`, `/usr/bin/dsc` might be found before the DiscoDOS wrapper. Change `$PATH` to first search in `~/.local/bin` (export it in `.zshrc`, `.bashrc` or whatever shell you are using)_ Launch DiscoDOS' main command: -`disco` +`dsc` -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](INSTALLATION.md#configure-discogs-api-access), then come back here! +On first launch, `dsc` 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](INSTALLATION.md#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). @@ -180,7 +180,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria Your starting point for further documentation is the [Quickstart Guide](QUICKSTART.md#importing-your-discogs-collection). 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: The `dsc` 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/`:** diff --git a/sphinx/source/INSTALLATION.md b/sphinx/source/INSTALLATION.md index d7bbba9..47b4860 100644 --- a/sphinx/source/INSTALLATION.md +++ b/sphinx/source/INSTALLATION.md @@ -26,9 +26,9 @@ Download the latest Windows installer (`DiscoDOS_version.exe`) from the [release Click Start Menu - DiscoDOS - DiscoDOS -A new command prompt window opens and the DiscoDOS main command `disco` runs automatically. +A new command prompt window opens and the DiscoDOS main command `dsc` 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](#configure-discogs-api-access), then come back here! +On first launch, `dsc` 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](#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). @@ -39,7 +39,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria Your starting point for further documentation is the [Quickstart Guide](QUICKSTART.md#importing-your-discogs-collection). 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: The `dsc` 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):** @@ -60,7 +60,7 @@ I would highly recommend installing "Microsoft Windows Terminal". It will provid - 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`) + - Zoom in/out (resize terminal text) using "ctrl + mouse wheel" (e.g handy when showing mixes in verbose view (`dsc 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) @@ -77,9 +77,9 @@ Doubleclick the .dmg file - Drag and drop `DiscoDOS.app` to `Applications` folde Launch DiscoDOS.app -A new Terminal window opens and the DiscoDOS main command `disco` runs automatically. +A new Terminal window opens and the DiscoDOS main command `dsc` 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](#configure-discogs-api-access), then come back here! +On first launch, `dsc` 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](#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). @@ -89,7 +89,7 @@ If the connection to Discogs is working, setup asks you to view a little tutoria Your starting point for further documentation is the [Quickstart Guuide](QUICKSTART.md#importing-your-discogs-collection). 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: The `dsc` 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/`:** @@ -115,7 +115,7 @@ To access your Discogs collection you need to generate an API login token and pu - Select _Settings_ - Switch to section _Developers_ - Click _Generate new token_ -- Run `disco` - you'll be prompted to put in the token. +- Run `dsc` - 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!** diff --git a/sphinx/source/MANUAL.md b/sphinx/source/MANUAL.md index e60d11d..6c56ef1 100644 --- a/sphinx/source/MANUAL.md +++ b/sphinx/source/MANUAL.md @@ -2,9 +2,9 @@ # User's Manual - [General things about command line tools](#general-things-about-command-line-tools) -- [*disco* - the main command](#disco---the-main-command) - - [*disco* - global switches](#disco---global-switches) -- [The *disco* subcommands](#the-disco-subcommands) +- [*dsc* - the main command](#dsc---the-main-command) + - [*dsc* - global switches](#dsc---global-switches) +- [The *dsc* subcommands](#the-dsc-subcommands) - [The *mix* command](#the-mix-command) - [The *suggest* command](#the-suggest-command) - [The *import* command](#the-import-command) @@ -24,69 +24,69 @@ This document contains in-detail explanations about everything you can do with D ## 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: +In case you don't use command line tools much: `dsc` is designed as such and thus each option has a short form and a long form. For example the help output of the dsc main command can be written two ways: -`disco --help` or `disco -h` +`dsc --help` or `dsc -h` another example: -`disco suggest --bpm 123` is the same as `disco suggest -b 123` +`dsc suggest --bpm 123` is the same as `dsc 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` +`dsc mix new_mix -c` is the same as `dsc 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` +`dsc search "search terms" -m new_mix -t A2` is the same as -`disco search "search terms" -t A2 -m new_mix ` +`dsc search "search terms" -t A2 -m new_mix ` -## *disco* - the main command +## *dsc* - the main command -DiscoDOS' main command is `disco`, to view it's help: +DiscoDOS' main command is `dsc`, to view it's help: -`disco -h` +`dsc -h` It contains four subcommands, namely: mix , suggest, import, search To execute a subcommand you would eg type: -`disco search ...` +`dsc search ...` Each subcommand has its own built-in help output: ``` bash -disco mix -h -disco suggest -h -disco import -h -disco search -h +dsc mix -h +dsc suggest -h +dsc import -h +dsc search -h ``` -### *disco* - global switches +### *dsc* - global switches -The general behaviour of `disco` can be altered by some "optional arguments": +The general behaviour of `dsc` 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 ...` +`dsc -v ...` or `dsc -vv ...` DiscoDOS checks if it's online automatically but can be forced to stay in offline mode: -`disco -o ...` +`dsc -o ...` -## The *disco* subcommands +## The *dsc* subcommands Each subcommand has its typical purpose but some actions can be executed from within other subcommands as well. @@ -103,77 +103,77 @@ A mix is basically just a list of tracks in a specific order, a playlist, a trac 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` +`dsc mix my_mix -c` Delete a mix (yes, it's a capital D): -`disco mix my_mix -D` +`dsc 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` +`dsc mix my_mix --copy` Edit general mix info (venue, played date): -`disco mix my_mix -E` +`dsc 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](#search-action-add-track-to-mix) as well: -`disco mix my_mix -a "search terms"` +`dsc 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` +`dsc 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` +`dsc mix my_mix -e 3` Delete 3rd track in the mix: -`disco mix my_mix -d 3` +`dsc 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` +`dsc 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` +`dsc mix my_mix -b trans_rating,bpm,key -p 3` Get track names for whole mix from Discogs: -`disco mix my_mix -u` +`dsc 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` +`dsc mix my_mix -u -p 3` Get additional track info for whole mix from MusicBrainz/AcousticBrainz (key, bpm, links): -`disco mix my_mix -z` +`dsc 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` +`dsc mix my_mix -z -p 3` Run a "detailed *Brainz match" (more likely to find matches but significantly slower) -`disco mix my_mix -zz` +`dsc mix my_mix -zz` Get track names for _all_ tracks in _all_ mixes from Discogs: -`disco mix -u` +`dsc mix -u` Get MusicBrainz/AcousticBrainz info for _all_ tracks in _all_ mixes from Discogs. Do a "detailed *Brainz match" run: -`disco mix -zz` +`dsc mix -zz` *Brainz matching is a tedious process for DiscoDOS (more details on this [here](#the-import-command)), 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` +`dsc mix -zz --resume 150` @@ -185,29 +185,29 @@ The suggest command helps a DJ find possible track combinations by reporting how 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"` +`dsc 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` +`dsc 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"` +`dsc 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` +`dsc 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` +`dsc suggest -b 120` key and BPM search can be combined: -`disco suggest -k Dm -b 120` +`dsc 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** @@ -222,31 +222,31 @@ Due to the Discogs API being not the fastest, it takes some time though. There a _**Note: This imports all your releases, but not the tracks on them**_ -`disco import` +`dsc 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` +`dsc 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` +`dsc 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` +`dsc 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` +`dsc 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](https://github.com/JOJ0/discodos/issues): -`disco import -zz` +`dsc 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. @@ -254,7 +254,7 @@ Also note that often it happens that a MusicBrainz track _can_ be "matched" but 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` +`dsc import -zz --resume 2500` The "*Brainz match process" currently adds the following data to releases: @@ -280,7 +280,7 @@ As the name implies, this command searches in your collection. By default it use To search an album of artist "Amon Tobin" you would type: -`disco search "Amon Tobin Foley Room"` +`dsc search "Amon Tobin Foley Room"` You will see the Album's details and its contents. @@ -288,7 +288,7 @@ _**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"` +`dsc 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. @@ -307,47 +307,47 @@ To "do" something with a track on an album you need to append an "optional argum To edit the track's details in the DiscoBASE you use: -`disco search "Amon Tobin Foley Room" -e` +`dsc 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` +`dsc 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` +`dsc 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"` +`dsc 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): +As a shortcut you can always just use the mix's ID number (you see the numbers in the output of the `dsc mix` command): -`disco search "Amon Tobin Foley Room" -m 27` +`dsc 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` +`dsc 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: +As already mentioned already, DiscoDOS is minimalistic by default. The default import command `dsc 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` +`dsc search "Amon Tobin Foley Room" -u` Again, combination with -t is possible: -`disco search "Amon Tobin Foley Room" -u t A2` +`dsc 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` +`dsc search all -u` -_**Note: This is exactly the same as using `disco import --tracks` or in short: `disco import -u`.**_ +_**Note: This is exactly the same as using `dsc import --tracks` or in short: `dsc import -u`.**_ Read more on importing release and track information in the [import command section](#the-import-command) @@ -357,21 +357,21 @@ 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](#search-action-update-from-discogs) action above.**_ -`disco search "Amon Tobin Foley Room" -z` +`dsc 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` +`dsc 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` +`dsc 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 +dsc search all -z +dsc search all -zz ``` Read more on the performance of the *Brainz match process and what exactely it imports in the [import command section](#the-import-command) diff --git a/sphinx/source/QUICKSTART.md b/sphinx/source/QUICKSTART.md index 09582ea..cc5ec49 100644 --- a/sphinx/source/QUICKSTART.md +++ b/sphinx/source/QUICKSTART.md @@ -26,11 +26,11 @@ Please head over to the [INSTALLATION](INSTALLATION.md) document for step by ste 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` +`dsc import` ## Commands Chart -Before you move on with the [Basic Usage Tutorial](#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. +Before you move on with the [Basic Usage Tutorial](#basic-usage-tutorial) have a look at the following picture. It shows how `dsc` - The DiscoDOS' main command - is working. Usually a `dsc` 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](../../assets/discodos_cmds_v0.3_transp.png) @@ -40,15 +40,15 @@ Before you move on with the [Basic Usage Tutorial](#basic-usage-tutorial) have a When importing is through, create a new mix: -`disco mix my_mix -c` +`dsc mix my_mix -c` View your (empty) mix: -`disco mix my_mix` +`dsc 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"` +`dsc 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. @@ -56,31 +56,31 @@ Be precise when asked for the track number on the record: A1 is not the same as 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` +`dsc 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` +`dsc mix my_mix -u` Use the verbose mode to see all the details pulled from Discogs: -`disco mix my_mix -v` +`dsc 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` +`dsc mix my_mix --help` Edit details of the third track in your mix: -`disco mix my_mix -e 3` +`dsc 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](MANUAL.md#the-mix-command) Get additional data about your mix's tracks from MusicBrainz and AcousticBrainz (key, BPM, links): -`disco mix my_mix -zz` +`dsc mix my_mix -zz` Read more about the *Brainz update process here: [The import command](MANUAL.md#the-import-command) @@ -94,25 +94,25 @@ This section guides you through typical DiscoDOS workflows. If you would rather 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` +`dsc 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"` +`dsc 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` +`dsc 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` +`dsc 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` +`dsc 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.**_ @@ -126,11 +126,11 @@ You're in the process of compiling a mix for a gig. You just played this one tun DiscoDOS can tell you in what combinations you ever played this tune in the past: -`disco suggest "search terms to find the tune"` +`dsc 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` +`dsc 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](MANUAL.md#search-action-update-from-brainz) search action**_ @@ -142,7 +142,7 @@ You are listening to a recording of a mix you have already documented into Disco Use the bulk-edit function to change specific fields of your mix's tracks: -`disco mix "the mix name" -b trans_rating,trans_notes` +`dsc mix "the mix name" -b trans_rating,trans_notes` Learn more about this function in the [mix command section](MANUAL.md#the-mix-command). @@ -154,25 +154,25 @@ _**Note: Currently DiscoDOS rating analysis system is not finished. This will be 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` +`dsc import 123456` Get artist/title for each track -`disco search 123456 -u` +`dsc search 123456 -u` Get key and BPM from MusicBrainz/AcousticBrainz: -`disco search 123456 -zz` +`dsc 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` +`dsc 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` +`dsc mix fat_mix -a 123456` @@ -182,7 +182,7 @@ As you've probably learned already, DiscoDOS doesn't import all information abou To make a full import of your whole record collection from Discogs (all releases INCLUDING all tracks on them) execute: -`disco import --tracks` +`dsc import --tracks` _**Note: This command can also be used for an initial import (you just started using DiscoDOS - DiscoBASE is still empty).**_ @@ -190,7 +190,7 @@ _**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` +`dsc import --zz` _**Note: This command requires the import-tracks command above, being completed already.**_ @@ -202,11 +202,11 @@ Here's a trick to execute both commands one after the other. We use the "command On Windows, do: -`disco import --tracks & disco import -zz` +`dsc import --tracks & dsc import -zz` on macOS or Linux it's: -`disco import --tracks && disco import -zz` +`dsc import --tracks && dsc 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](https://github.com/JOJ0/discodos/issues), it would help me a lot to state more accurate estimates here. diff --git a/sphinx/source/disco.rst b/sphinx/source/dsc.rst similarity index 82% rename from sphinx/source/disco.rst rename to sphinx/source/dsc.rst index 010d694..2a44f40 100644 --- a/sphinx/source/disco.rst +++ b/sphinx/source/dsc.rst @@ -1,4 +1,4 @@ .. autoprogram:: discodos.cmd.cli:ArgParse.parser - :prog: disco + :prog: dsc :maxdepth: 0 :groups: \ No newline at end of file diff --git a/sphinx/source/index_commands_reference.rst b/sphinx/source/index_commands_reference.rst index 59e24bc..84c9f5e 100644 --- a/sphinx/source/index_commands_reference.rst +++ b/sphinx/source/index_commands_reference.rst @@ -4,5 +4,5 @@ Commands Reference .. toctree:: :maxdepth: 6 - disco + dsc discosync From a4708eb0375f3493b9a872712a012d53590eca32 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 23 Jul 2024 15:04:02 +0200 Subject: [PATCH 2/3] Add .readthedocs.yaml and fix year in sphinx conf.py --- .readthedocs.yaml | 24 ++++++++++++++++++++++++ sphinx/source/conf.py | 2 +- 2 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..dd1a64c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,24 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: sphinx/source/conf.py + +# We recommend specifying your dependencies to enable reproducible builds: +# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: ./sphinx_requirements.txt + - method: pip + path: . diff --git a/sphinx/source/conf.py b/sphinx/source/conf.py index 7ab1316..4dbe318 100644 --- a/sphinx/source/conf.py +++ b/sphinx/source/conf.py @@ -22,7 +22,7 @@ # -- Project information ----------------------------------------------------- project = 'DiscoDOS - the geekiest DJ tool on the planet' -copyright = '2018-2022, J0J0 Todos' +copyright = '2018-2024, J0J0 Todos' author = 'J0J0 Todos' # The short X.Y version From c405301ec4004c7384da28d4a40337c331398ed7 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 23 Jul 2024 15:29:37 +0200 Subject: [PATCH 3/3] Note AcousticBrainz shutdown in README but don't bother to remove all instances from Sphinx docs for now -> A quickfix! --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e842656..f699bd6 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ D i s c o / / / - The geekiest DJ tool on the planet /_______/\_______/________/ ``` -DiscoDOS helps a DJ remember and analyze what they played in their sets, or what they could possibly play in the future. It's based on data pulled from a users [Discogs](https://www.discogs.com) record [collection](https://support.discogs.com/hc/en-us/articles/360007331534-How-Does-The-Collection-Feature-Work-). Tracks can be organized into playlists and mix-transitions rated. Additionally the collection can be linked to the online music information services [MusicBrainz](https://musicbrainz.org) and [AcousticBrainz](https://acousticbrainz.org), thus further information (like musical key and BPM) is made available to the user. +DiscoDOS helps a DJ remember and analyze what they played in their sets, or what they could possibly play in the future. It's based on data pulled from a users [Discogs](https://www.discogs.com) record [collection](https://support.discogs.com/hc/en-us/articles/360007331534-How-Does-The-Collection-Feature-Work-). Tracks can be organized into playlists and mix-transitions rated. Additionally the collection can be linked to the online music information services [MusicBrainz](https://musicbrainz.org) ~~and [AcousticBrainz](https://acousticbrainz.org), thus further information (like musical key and BPM) is made available to the user~~. DiscoDOS currently is available as a command line tool only, though prototypes of a mobile and a desktop app exist already. Despite of what the name implies, it's just the look that is reminiscent of the 80s/90s operating system, its usability follows most standards of a typical [shell](https://en.wikipedia.org/wiki/Shell_(computing)#Unix-like_systems) utility you would find on a [UNIX-like operating system](https://en.wikipedia.org/wiki/Unix-like). @@ -19,6 +19,10 @@ DiscoDOS primarily aims at the Vinyl DJ but feature ideas for DJ's playing both, The following animated GIFs should give you an idea on how DiscoDOS looks and feels: +_**Note: As of February 2022 unfortunately [the AcousticBrainz project was shut down](https://blog.metabrainz.org/2022/02/16/acousticbrainz-making-a-hard-decision-to-end-the-project/), as a consequence DiscoDOS can't fetch key and BPM anymore. Below videos are outdated and show some of those features.**_ + +_**Note: Find some ideas on how DiscoDOS could solve this problem [in the website's roadmap chapter](https://discodos.jojotodos.net/#roadmap).**_ + ##### Viewing mix details, searching and adding track: