-
Notifications
You must be signed in to change notification settings - Fork 600
Usage guide
First off, this usage guide is written by an author that installed Headphones under Ubuntu 14.04. Therefore, some steps may differ from your installation.
There are some terms you need to know to understand how Headphones works.
Headphones is an automated music downloader. It uses public music databases to fetch artist and album information. This information is then used to snatch download from search providers (NZB and Torrent). Headphones does NOT download music, it only automates the download process.
The public music databases are MusicBrainz and Last.FM. When you search for an artist or album, it will query MusicBrainz. This database references information by ID's that look similar to this one: 2386cd66-e923-4e8e-bf14-2eebe2e9b973. Artist information and covers are requested from Last.FM.
An album is refered to as a release group, because one album can have multiple releases (for instance, an Europe version, Japanese version etc). When you add an artist or album, Headphones will try to merge all releases into a so-called "Hybrid" release, that should be suitable for matching.
If you want to change artist or album information, you can contribute to MusicBrainz.
You might want Headphones to import your existing library. You can do this by heading over to the "Manage" page and check the "Scan Music Library" tab. Make sure to check the "Automatically scan library" and "Auto-add new artists". As soon as you click "Save changes and scan", Headphones will read your library.
Alternatively, you can go to the "Import" tab to import your Last.FM artists. Enter your username, and click "Send". Headphones will now import your artists!
When Headphones searches for downloads, NZBs or Torrents will be sent to your download client. Once in a while, Headphones will check if downloads are finished by looking in the "Post processing folder". Headphones expects each download to be in a separate folder, without any subfolders. Then, it will take an initial guess for the Artist and Album according to these rules:
- If Headphones snatched the download, it will try to find the folder by the download title.
- If that fails, it will parse the folder name according to some format. A good folder name is
Artist - Album [Year]. - If that fails, it will look at the metadata of the songs inside that folder. If the majority of the metadata is the same, it will continue. Headphones expects a structure like
Album Folder/[CD X/]/Some Audio File.Ext. - If that fails, it will try take the "Release Group ID" from the folder name.
- If that fails, it will just try the folder name.
If it has a guess, it will verify the guess. Verification means it will scan the file names, track lengths and more, and make sure it matches the release it guessed. If this fails, the folder will be marked as unprocessed. Parsing file names may be easy for humans, but may be hard for computers. Sometime you just have to help.
When it continues, the next step is the actual post processing. Files will be renamed, moved and corrected according to your preferences.
In the last step, it will "match" the files and mark it as downloaded. Sometimes a download does not match a specific releas. For instance, one release has 13 tracks, but your download has only 12. If you visit a release page, you can switch a release, so it will match properly.
Click on the Gear Icon in the tab. That will bring you to a screen where you can configure Headphones to correctly on your system. You can change multiple settings under different tabs. When you are finished, click "Save Changes".
We will describe the different tabs below.
The first thing you may want to modify is the network settings. This includes the host, port, username and password, and whether or not you want a browser to launch when Headphones starts.
You probably won't need to modify the the port, but if you have something else running on port 8181, change the 'HTTP Port' setting to something else.
If you want to secure access to Headphones, set a username and password. You will be prompted to enter this information after a restart.
If you want to start Headphones without a browser launching each time, uncheck the 'Launch Browser on Startup' option.
For security reasons, Headphones will serve on localhost by default. This means you cannot access Headphones from another computer unless you change host to 0.0.0.0.
Headphones supports NZBs and Torrents. Furthermore, there are two ways of downloading. The first method communicates with a download program directly. The second way is called "Black Hole", where Headphones will drop the NZB or Torrent into a watch folder. The first method is preferred and most stable.
Select your favorite download options, and enter the required credentials.
The "Music download folder" is the folder where your download client will store the completed downloads. This is the folder Headphones will check to process the files. Make sure that both Headphones and your download client can write to the same files. The "Music download folder" is also refered to as the "Post processing folder".
Warning: Do not set you "Music Download Folder" to the (final) destination folder! This may delete all your files.
Enter all your relevant search providers information here. Make sure to check the boxes for the providers you want to use. If you're using Newznab, enter the hostname such as 'http://nzb.su'
There are four options for album quality choice when downloading:
- Highest Quality excluding Lossless: This option will download the highest quality MP3 versions of the albums you want.
- Highest Quality including Lossless: This option will try to download a FLAC version of the albums you want, but if it can't find them, it will download the MP3 version.
- Lossless Only: This option will look only look for FLAC versions, and won't download anything less!
- Preferred Bitrate: You can set a target bitrate (good for those who like VBR!) and it will find the version of the album that is as close to the right size as possible, based on the duration of the particular album. If you check 'Auto-Detect bitrate', Headphones will try to figure out what bitrate your music collection is in during the next music scan (we'll get to that later)
If you have a lot of false matches, you probably want to use the last option!
You can enter words that should be ignored in the title of the downloads that Headphones encounters. Words are separated by comma's.
For the post processing, there are a lot of options. Check the options as you like. The option "Freeze database for adding new artists" makes sure new artists are not added to your collection if Headphones finds artists in the post processing folder.
The "Path to Destination Folder" is the folder where Headphones will move all file to if you have checked "Move downloads to Destination Folder".
There are several notification options available. You can enable multiple notification services if you want.
These settings should only be considered if you have Headphones running and if you know what you are doing. Changing the settings may result in a corrupted library.
Under "Re-Encoding Options", you can select your favorite encoder, in case you want to re-encode files (e.g. lossless to MP3). Headphones assumes it can find the encoder on your path, so make sure it is installed.
The default extras that are fetched can be set under "Miscellaneous". File permissions can also be changed here. Note that the file permissions are in octal notation.
If you have troubles with the MusicBrainz mirror, you can change it under "Musicbrainz". In case you use a custom server, respect the "Sleep Interval", so you won't hammer the remote server.