Home

Awesome

wincalibre2jellyfin

Python script to construct a Jellyfin ebook library from a Calibre library.

Windows

<em>(The Linux version of this script is maintained as a separate project. Please see calibre2jellyfin).</em>

Overview

Example author/series/book structure

Example assumes script has been configured to prefer .epub types over .azw and .mobi.

<table> <thead> <tr><th>Calibre store</th><th>Created Jellyfin store</th></tr> </thead> <tbody> <tr> <td><pre> └── Author\ └── Book A\ │ ├── cover.jpg │ ├── metadata.opf │ ├── Book A.azw │ └── Book A.epub ├── Book B\ │ ├── cover.jpg │ ├── metadata.opf │ ├── Book B.mobi │ └── Book B.epub </pre> </td> <td><pre> └── Author\ └── Lorem ipsum dolor sit amet Series\ ├── 001 - Book A\ │ ├── cover.jpg <- copy │ ├── metadata.opf <- modified copy │ └── Book A.epub <- copy ├── 002 - Book B\ │ ├── cover.jpg <- copy │ ├── metadata.opf <- modified copy │ └── Book B.epub <- copy </pre> </td> </tr> </tbody> </table> Jellyfin will display a drillable folder structure similarly to the way it does for movies, shows, and music. Jellyfin will extract, display, and sort by the mangled book title that is prepended with the series index.

Example series/book structure

The "series/book" option is intended for use with eComics, thanks for this go to Cudail.

<table> <thead> <tr><th>Calibre store</th><th>Created Jellyfin store</th></tr> </thead> <tbody> <tr> <td><pre> └── Author M\ └── Comic A\ ├── cover.jpg ├── metadata.opf └── Comic A.cbz └── Author N\ └── Comic B\ ├── cover.jpg ├── metadata.opf └── Comic B.cbz </pre> </td> <td><pre> └── Lorem ipsum dolor sit amet Series/ ├── 001 - Comic A\ │ ├── cover.jpg <- copy │ ├── metadata.opf <- modified copy │ └── Comic A.cbz <- copy ├── 002 - Comic B\ │ ├── cover.jpg <- copy │ ├── metadata.opf <- modified copy │ └── Comic B.cbz <- copy </pre> </td> </tr> </tbody> </table>

Changes

Dependencies

Installation

  1. In your browser navigate to "https://github.com/shawn61cp/wincalibre2jellyfin"
  2. Click the green "Code" button
  3. In the resulting dropdown, just over halfway down, find and click on "Download ZIP".
  4. Save the zip file somewhere convenient, your Documents folder is suggested, and extract it. We will call this EXTRACT_FOLDER.

Usage

Upgrading

Two things need to be accomplished:

  1. Replace your current script, wherever it was originally installed, with the new one.
    • This can be done basically by following the installation steps but you may need to extract the new zip file to a location other than the one you used originally in order to ensure that your existing configuration is not destroyed. Once the new zip file is extracted safely, you can copy only the new script over the top of the original script.
  2. Add any new config options to your existing configuration file.
    • This can be done by copying and pasting any new configuration parameters from the new sample configuration into your current configuration, or even just editing your current configuration. New configuration options are listed in the Changes section and also in the sample .cfg file.

Command line options

<pre> usage: calibre2jellyfin.py [-h] [--debug] [--dryrun] [--invert] [--list LIST_SPEC] [--update-all-metadata] [-v] A utility to construct a Jellyfin ebook library from a Calibre library. Configuration file "wincalibre2jellyfin.cfg" is required. options: -h, --help show this help message and exit --debug Emit debug information. --dryrun Displays normal console output but makes no changes to exported libraries. --invert Inverts the sense of the --list argument, showing those items that will not be exported. Only valid in combination with --list. --list LIST_SPEC Suspends normal export behavior. Instead prints info from configuration sections and file system that is useful for curation. LIST_SPEC is a comma- delimited list of columns to include in the report. The output is tab- separated. Columns may be one or more of authors, section, book, bfolder, afolder, subject, series, or index. authors: display author name if the source folder exists. section: display section name. book: display book title. bfolder: display book folder. afolder: display author folder. subject: display subject that matched. series: display name of the series. index: display series index. The report output is sorted so there will be a pause while all configured sections are processed. --update-all-metadata Useful to force a one-time update of all metadata files, for instance when configurable metadata mangling options have changed. (Normally metadata files are only updated when missing or out-of-date.) -v, --version Display version string. </pre>

Real Life

The installation and usage instructions above work fine but other situations may be encountered or other conveniences desired.

Calibre Author Folders

If you find that an expected author does not show up in the created Jellyfin library, double check that the author as listed in the .cfg file matches the actual folder name in the Calibre library.

In the case of multiple authors, Calibre expects them to be delimited by an ampersand and, I believe, a space on either side (" & "). If you acquired metadata with multiple authors delimited by commas, replace the commas with space-ampersand-space, but keep commas that separate name suffixes like Jr./Sr./PhD/MD etc. Using ampersands as delimiters accomplishes two things. First, Calibre will recognize each author and list them properly and individually in its author browser. Second, Calibre will name the author folder after the first author in the list, keeping your on-disk Calibre and Jellyfin libraries nice and clean, as opposed to the lengthy run-on name that results otherwise.

Another thing I have encountered is when multiple versions of the author name exist, such as "Public, John Q." and "John Q. Public", and they are then consolidated, Calibre actually moves the books into the folder matching the consolidated name. If the author name configured for calibre2jellyfin happened to match the author name that "went away", updates to that author's books may appear to die, or you might see two different versions of the same author in Jellyfin. The solution is to just delete, in Jellyfin, one or both authors, ensure that the author configured in the .cfg file matches the Calibre author folder, then re-run the script to have them cleanly re-created. Jellyfin will eventually detect the changes and update the display contents. You can also right-click on an item within Jellyfin and request an immediate metadata refresh. Even so sometimes it will take a few minutes for Jellyfin to recognize the changes.

Tricks with [Construct] jellyfinStore

Although the instructions in the example .cfg file state categorically that the jellyfinStore parameter should be set to the location of the Jellyfin library, there actually is some wiggle room.

Suppose that you want top level folders in your Jellyfin library that separate your fiction library into "Science Fiction", "Fantasy", "Westerns", and "Romance". You could create the following structure for the Jellyfin library and then create separate [Construct] sections for each top level category.

<pre> ...\fiction\ <- point the Jellyfin library here ├── Fantasy\ <- point a [ConstructFantasy] jellyfinStore param here ├── Romance\ <- point a [ConstructRomance] jellyfinStore param here ├── Science Fiction\ <- point a [ConstructSciFi] jellyfinStore param here └── Westerns\ <- point a [ConstructWesterns] jellyfinStore param here </pre>

Then using your desired selectionMode, arrange for appropriate books to be output from each [Construct...] section. Jellyfin would then display drillable category folders above the author folders (or whatever folderMode you choose).

Mature Content

Selection by author, although good for this purpose, is not exactly 100% perfect since it is possible for a single author to write content of differing level.

Selection by subject gives finer grained control but tags are often missing and when present seem inconsistent. To really make selection-by-subject work you would probably have to curate tags yourself.

Another approach would be to combine construction methods. Nothing prevents having multiple [Construct] sections that output to the same Jellyfin library. (You probably would want to use the same foldermode.) One could exclude problematic authors (No offense, authors!) from a selection-by-author [Construct] and then handle those within a selection-by-subject [Construct].

Curation

None of these reports and lists are at all required in order to use the wincalibre2jellyfin script. I use them when I review my Calibre library for things that need to be cleaned up.

<strong><em><ins>Caveat Usor:</ins></em></strong> Several of the following procedures use sqlite3 to access the Calibre metadata database directly. Read-only select statements should not present problems. Nevertheless it is a good idea to make a backup of such an important file.

Prerequisites

The reports described here require the sqlite3 command shell and a couple unix utilities. To install them follow these instructions.

Listing Calibre author folders etc. that will <em>not</em> be output by calibre2jellyfin.

The --list option together with the --invert option report items that will not be exported. I use this as my to-do list.

Compact list of Calibre author's series

<pre>sqlite3 -column "PATH_TO_CALIBRE_LIBRARY\metadata.db" "select A.name as author, S.name as series from authors A inner JOIN books_authors_link BAL on BAL.author = A.id inner JOIN books_series_link BSL on BSL.book = BAL.book inner JOIN series S on S.id = BSL.series group by A.name, S.name order by 1, 2 ;"|less -S</pre>

Compact list of Calibe series

<pre>rem With authors sqlite3 -column "PATH_TO_CALIBRE_LIBRARY\metadata.db" "select distinct S.name as series, (select group_concat(A.name, ',') from books_authors_link BAL inner join authors A on A.id = BAL.author where BAL.book = B.id) as authors from books B inner join books_series_link BSL on BSL.book = B.id inner join series S on S.id = BSL.series order by 1, 2;" | less rem With author folder sqlite3 -column "PATH_TO_CALIBRE_LIBRARY\metadata.db" "select distinct S.name as series, substr(B.path, 1, instr(B.path, '/')-1) as afolder from books B inner join books_series_link BSL on BSL.book = B.id inner join series S on S.id = BSL.series order by 1, 2;" | less </pre>

Compact list of Calibre author's books

<pre>sqlite3 -column "PATH_TO_CALIBRE_LIBRARY\metadata.db" "select A.name as author, B.title as book, coalesce(S.name, '') as series from authors A inner join books_authors_link BAL on BAL.author = A.id inner join books B on B.id = BAL.book left join books_series_link BSL on BSL.book = B.id left join series S on S.id = BSL.series order by 1, 2;"|less -S</pre>

Compact list of Calibre collaborator's books

<pre>sqlite3 -column "PATH_TO_CALIBRE_LIBRARY\metadata.db" "select (select group_concat(A.name, ',') from books_authors_link BAL inner join authors A on A.id = BAL.author where BAL.book = B.id) as authors, B.title as book, coalesce(S.name, '') as series from books B left join books_series_link BSL on BSL.book = B.id left join series S on S.id = BSL.series order by 1, 2;"|less -S</pre>

Differences between Linux and Windows versions

The Windows and Linux code is probably 99 point something percent identical but there are a few differences.

Odds and Ends