Attachments

Here, we'll design the oft-requested attachments feature (see #111).

Important use cases

Upon import of audio files into the Beets library, users may wish to...

• Move the accompanying .log file into the same directory as the imported audio files.
• Move the accompanying .CUE file into the same directory as the imported audio files.
• Move album artwork associated with the audio files.
  • There could be multiple image files.
• Have the ability to move arbitrary files associated with the audio files, by way of a prompt questioning the user whether or not to import 'file-x.x' or by way of user declaration in an optional command, "include files of .xx".
• Declare a white list of file extensions they wish to import with the audio files.
• Support sub-directories
• Enable copy/move of Artist level images to corresponding Artist in beets structure, that is if pinkfloyd.jpg is present in the pink floyd artist folder move it to the pink floyd root level in the beets output
• Be able to query the database to see all albums with attachments and those without. ie. Find all albums without a .log file (so a user can re-rip those albums, for example).
• Track the attachments in the database
  • Move the attachments (should attachments be allowed to be stored anywhere other than the album folder, or can we think of an example in which the user would want to associate an attachment with an album that would need to be stored elsewhere?)
  • Rename the attachments
  • Ability to query the database to see which attachments exist and where

Optional use cases

• A configuration option to convert auto-downloaded image formats to the preferred format of the user (jpg/png) would allow for easy standardization in filetypes. (Does this feature belong in the attachments section?)
• Incorporate a log checker function to be able to see a list of all "100% Accurate Rip" Logs and those that aren't 100%.
• Convert cue sheets / log files to UTF-8.
• If a log or cue file is found, rename the file to $artist - $album.cue/log or other given variables names.
• If several images are present in the original folder, put them in an "artwork" directory in the new library folder (front.jpg, back.jpg, cd.jpg). This however, may cause an issue with media players that rely on an artwork file in the same directory as the files being played.
• Possibility to use the CUE file to split large FLAC files
• Possibility to detect which attachments are meant to exist and those that are clutter

Beets functionality

Beets would need new functionality to cover the above use cases, this is a list of what Beets would need to do.

• Upon import, Beets would need to be able to analyse a folder and prompt the user that additional attachments exist.
• Beets would need to be able to offer options to the user when importing, ie. beets import --attachments=log,cue ...
• Include functionality so that Beets reviews the library filesystem and if attachments exist in folders (for example, users have manually copied these attachments over - common amongst users who use log files), that haven't been logged in the database, it should "import" them and associate them with the album in question.
• Include functionality so that existing attachments can be modified (renamed, moved(?), and queried/searched).

CLI Overview

Here's a general way that the CLI could be organized. Please feel free to edit this as necessary, as it's very much a work in progress.

beet import -attachments="jpg,cue,log"

A slight modification to the existing import function would be necessary, and would be largely preferred to using an attach command and doing everything manually. When importing normally, beets will also be scanning for files with extensions meeting those specified with the -attachments flag. If they are found, then they would be attached to the album exactly as if they were run through the beet attach command that follows.

beet attach [-cpe] [-i / -d] ATTACHMENT QUERY

This command will take a file or directory, and then attach it to the album(s) meeting the supplied query. All non-image files will be attached normally. In the case of an image file (jpg/png), beets will assume that they are some kind of artwork (front cover or otherwise), and then prompt the user to enter what kind of artwork they're supplying. Based on the wikipedia page here, there are a lot of different embedded image types ID3V2 supports that we should support. All artwork other than the front cover should be stored in an 'artwork' subdirectory in the album folder.

For cases other than artwork, we can account for a few of them. Common files would be .log files and .cue files. Beets can be on the lookout for these and rename as necessary (or as specified by user in config.yaml).

• -c, Copies the given attachment instead of moving it from its source location.
• -p, Pretend to attach everything, but don't actually modify anything.
• -e, If the user at any point is picking what kind of artwork is being attached, and they select the front cover, if this option is enabled, that front artwork will automatically be embedded into the media files of that album.
• [-a / -d], The attachment file(s), pick one but not both
  • -a, Short for attachment, this is the path to the attachment that is to be attached.
  • -d, Short for directory, this allows the user to attach all files located within a directory. Beets will parse each one individually, as if the user had used the single-file version of the command over and over again for each file in the directory.

###Examples Due to limitations of markdown, code blocks cannot contain bold text. When beets asks the user to pick the appropriate artwork type, each option will have bold letter which indicate what letters to use in order to select that type, exactly how the importer works now.

C:\Users\Joe> beet attach -ae -d "D:\artwork\" "humbug"
Searching "D:\artwork", found 4 files.
File 1: front.jpg (D:\artwork\front.jpg) - Please pick the appropriate artwork type:
    front, back, leaflet, media, artist, during_recording, during_performance, artist_logo, other
    Pick one: front
    Front cover specified and -e flag enabled, embedding artwork... success. 10 files embedded.
File 2: back.jpg (D:\artwork\back.jpg) - Please pick the appropriate artwork type:
    front, back, leaflet, media, artist, during_recording, during_performance, artist_logo, other
    Pick one: back
File 3: logo.jpg (D:\artwork\logo.jpg) - Please pick the appropriate artwork type:
    front, back, leaflet, media, artist, during_recording, during_performance, artist_logo, other
    Pick one: artist_logo
File 4: humbug.log (D:\artwork\logfile.log) - Log file detected
Library query had 1 result.
Arctic Monkeys - Humbug
    Attached folder.jpg (renamed from "front.jpg", stored as "D:\music\Arctic Monkeys\Humbug\folder.jpg")
    Attached back.jpg (stored as "D:\music\Arctic Monkeys\Humbug\artwork\back.jpg")
    Attached artist_logo.jpg (renamed from "logo.jpg", stored as "D:\music\Arctic Monkeys\Humbug\artwork\logo.jpg")
    Attached Humbug.log (renamed from "logfile.log", stored as "D:\music\Arctic Monkeys\Humbug\Humbug.log")

C:\Users\Joe>