Audio M3U Documentation
WORK IN PROGRESS, Sorry, documentation not yet complete.
The Audio M3U plugin is intended to allow you to easily maintain a library of audiobooks within Calibre. It supports MP3, M4A and M4B formats, and works by using a playlist file (M3U) as the 'format' of the book.
Once an audiobook has been added to Calibre as an M3U, the plugin can be used to fetch tag and file data from the audiofiles themselves to populate Calibre book fields. Standard fields such as title, author as well as cover artwork can be pulled from the audiofiles. By adding custom columns to the calibre library, you can also import a wide range of audio specific information, including file types, bitrates, sample rates, playing time, total number of files, and more.
The following is an example of a book details panel within Calibre showing additional fields which were populated automatically with the plugin:
Initially the Audio M3U plugin is ready to import and export title, author and book cover artwork between the audio files and the Calibre database. To take advantage of additional fields, they must be first enabled within the configuration menu, and assigned a custom column so that the plugin knows where to store the data. Custom columns can be added from Calibre's "Preferences->Add your columns" dialog. In order for a custom column to be useable to the plugin, it also has to be of the correct format. Different fields require different formats, as described below. If your columns are not set up correctly, the plugin will warn you and prevent you from importing or exporting metadata.
The cover field is built in to the Audio M3U plugin, and no additional configuration is required to use it. JPG and PNG image formats are both supported. When importing cover artwork from an audiobook with more than one file, the first file will be the one used as the source of the cover.
The book title field is built in to the Audio M3U plugin, and requires no additional configuration to use.
The author field is build in to the Audio M3U plugin, and requires no additional configuration to use. The author field in Calibre maps the the artist field in an audiofile. If there are multiple authors for an audiobook, the names should be separated with ' & ' in the audio file tag in order to be imported correctly. For exporting the field from Calibre, this is handled automatically.
The narrator field requires a custom column to be set up within the Calibre preferences dialog. The format of this column must be text. There are a lot of options for text field formats. This can be a simple text field by selecting a column type of 'Text, column shown in the Tag browser', however it's recommended to set this up to be 'Ampersand separated text, shown in the Tag browser' so that multiple narrator names can be specified, much like the author field. This can be done by first selecting 'Comma separated text, like tags, show in the Tag browser', and then clicking the 'contains names' checkbox.
There is no common narrator field in audio files, instead, the convention of storing the narrator names in the composer field of the audio files is used.
There are two options for how to store duration information. You can choose to use a text column, which stores the total playtime in an easily readable h:mm:ss format (see the example in the book details image above). If you prefer a format that's more easily sortable, you can also choose to store the total number of seconds in an integer column. This field is a sum total of the duration of all of the files in the audiobook.
There are two options for how to store the size information. You can choose to store it as a floating point number representing the total number of megabytes, or you can choose to store an integer value with the total number of bytes. Like duration, this is a sum total of the size of all of the files in the audiobook.
Tip: If using floating point, you can get a nicely formatted output in the book details window by specifying the display format as something like '{0:.1f} MB' (see below)
See the example in the book details image above to see what this looks like in the book details panel.
The sample_rate column stores the sample rate of the audio files in hertz. This is stored as an integer. Common values include 44100, 22050, 11025 etc. Generally the higher the simple rate, the better the quality, but the larger the file.
This stores the bitrate that the files are encoded in, measured in kbps. Generally the higher the bitrate, the higher the quality, but the larger the file. This must be an integer format column.
Tip: It is recommended to configure the the display format of the column to something like '{0:d} kbps' if desired, as shown below:
This column stores the mode that the audio files were recorded in, for example 'stereo', 'mono', 'joint stereo', etc. It is a text format column.
This column stores the type of the audio files. Supported file types include "MP3", "M4A" and "M4B". It is a text format column.
The num_files column stores the total number of audio files for the book in an integer field.
This column stores the genre of the audiobook in a text field. This can be a regular text field, or a 'Comma separated text field' if you want to be able to store more than one genre for a book.
The two options for this column primarily come into play when you are using 'subgroups', such as is commonly done with the genre field. If you have configured the column for subgroups (Calibre 'preferences->Look & Feel->Tag browser->Hierarchy and searching'), you can specify levels of genre hierarchy by delimiting them with the '.' character. For example, I could have a book assigned to a genre of 'Nonfiction.Science.Astronomy', which would allow me to browse and filter based on the different layers of hierarchy.
If 'Trim to Subgroup on Export' is selected, then when exporting genre metadata to an audio file, only the lowest subgroup would be exported. For the example above, 'Nonfiction.Science.Astronomy' would be converted to just the shorter 'Astronomy' when stored in the genre tag of the audio file. 'Expand Subgroup on Import' will do the opposite of this. In our example, if we imported 'Astronomy' as the genre, the plugin will scan through the tags and attempt to match anything that appears to be an expanded version. If 'Nonfiction.Science.Astronomy' existed in our database, then 'Astronomy' could be upconverted to this full hierarchical name on import. Note that if more than one genre matches, only the first is used.