Supported Formats

Shisho has native support for six main-file formats. See Reading and Playback for the in-app readers, Metadata for the fields Shisho manages, and Getting Started for library setup.

Capability Matrix

Format	Import	Metadata Extraction	In-App Reader or Player	Generated Download
EPUB	Yes	Package metadata, navigation, and embedded cover data	Ebook reader	EPUB with supported current metadata and edited chapters applied
CBZ	Yes	ComicInfo.xml, page images, and detected chapters	Comic reader	CBZ with supported current metadata applied
M4B	Yes	Audiobook metadata, chapters, audio details, and embedded cover data	Audiobook player	M4B with supported current metadata applied
PDF	Yes	Document metadata, page count, bookmarks, and a rendered cover	PDF reader	PDF with supported current metadata and bookmarks applied
MOBI (.mobi, .azw, .prc)	Yes	Embedded metadata, table of contents, and cover; see MOBI and AZW3	Ebook reader	MOBI with supported current metadata, cover, and edited chapters applied
AZW3 (.azw3)	Yes	Embedded metadata, table of contents, and cover; see MOBI and AZW3	Ebook reader	AZW3 with supported current metadata, cover, and edited chapters applied

Generated downloads are format-specific. Each format can represent a different set of metadata, so Shisho cannot write every database field or replace a cover in every generated file. The source file is not modified.

Downloads are sent with the format's media type, whatever the server's operating system knows about file extensions: application/epub+zip for EPUB and KePub, application/vnd.comicbook+zip for CBZ, audio/mp4 for M4B, application/pdf for PDF, application/x-mobipocket-ebook for MOBI, and application/vnd.amazon.mobi8-ebook for AZW3. Kobo Sync downloads are sent as application/octet-stream. Other files, such as supplements, are typed by their extension.

The OPDS, eReader, Kobo Sync, and Share Link downloads send the original file when a generated one cannot be made: for a supplement, a format only a plugin can read, a KePub request for M4B or PDF, or a file whose contents Shisho cannot rewrite, such as a damaged EPUB. The failure is written to the server log. A source file Shisho cannot read, for example because of its permissions, fails the download with an error instead. In the web app, a failed download reports an error, and Download Original sends the file as it is. See Troubleshooting.

CBR is not a native format. Using Plugins may add parsers or converters for CBR and other formats.

First Downloads

A generated download starts as soon as it is requested and is built while it is sent. EPUB, M4B, MOBI, AZW3, and PDF downloads know their size before they start, so the device or browser shows progress even the first time. A CBZ or a KePub, whether made from an EPUB or a CBZ, does not: its first download has no file size, so the device or browser cannot show a percentage, and an interrupted download starts over. Later downloads of the same file show their size while it stays in the download cache.

MOBI and AZW3

Kindle files are imported as two file types: MOBI for .mobi, .azw, and .prc files, and AZW3 for .azw3 files. A file keeps its own extension on disk, so an organized .azw file is still an .azw. A .mobi that holds both an older Mobipocket book and a newer KF8 book, as Calibre writes with its "both" output type, is read from the KF8 book.

A scan reads these fields from the file:

• Title
• Authors, with "Last, First" names such as Doe, Jane turned into Jane Doe
• Description, with HTML removed
• Publisher, using the imprint when the file has one
• Release date and language
• ISBN and ASIN identifiers
• Subjects, as genres, split on ;
• The embedded cover
• The table of contents, as chapters with their nesting. Calibre writes the table of contents of an older Mobipocket book flat, so a .mobi converted by Calibre without a KF8 book has no nested chapters.

Series, tags, and author roles have no place in these formats. Set them through sidecar files, metadata plugins, or your own edits.

Downloads write the same fields back into the file, with Shisho's current values: title, authors, description, publisher, release date, language, ISBN and ASIN, genres, and the cover. A field Shisho has no value for keeps the value already in the file. Series, tags, author roles, and narrators are not written, and the series is never added to the title. In a combo .mobi, both books get the new metadata and chapter edits, so a Kindle shows them whichever book it opens. A file with no cover gets one. Covers are written as JPEG, because older Kindles cannot show a PNG. Some older files store text as Windows-1252; a character that encoding cannot hold, such as one from a non-Latin script, is written as ? in those files.

A generated download is named with its file type, so an .azw or .prc file downloads as .mobi. Download Original keeps the file's own name.

DRM-protected files are never imported. Each one is named in the scan's job log; see Troubleshooting. KFX, Topaz, and other Kindle formats that are not MOBI or AZW3 are skipped, even when they use the .azw extension.

CBZ Page Images

Native CBZ parsing recognizes these page image formats:

• PNG
• JPEG (.jpg and .jpeg)
• WebP
• GIF

Pages are read in file name order, folder names included, with numbers compared by value: page2.jpg comes before page10.jpg, and Chapter 2/ before Chapter 10/. macOS metadata such as ._page1.jpg files and anything under __MACOSX/ is not a page. The reader, the ComicInfo.xml cover index, and KePub downloads count pages in this order, and so do the cover page and chapter start pages that a scan records. A comic scanned by an earlier version can keep cover page and chapter numbers counted the old way; see Troubleshooting.

PDF Bookmarks

Scanning a PDF turns its bookmarks into chapters, flattened into a single list. A bookmark that does not point at a page is skipped. Its nested bookmarks are still imported when they point at pages.

PDF Downloads

A downloaded PDF is the original file, unchanged, with Shisho's metadata and bookmarks appended to the end as an update. PDF readers show the appended title, authors, description, tags, language, and chapters. Because the original bytes are kept, the file is not re-optimized, so it can be slightly larger than the original. A PDF optimized for fast web viewing (linearized) loses that optimization, so a browser may need the whole file before it shows the first page. A digital signature still covers the original bytes and verifies, though PDF readers report the document as changed after signing, and a certified PDF that permits no changes is shown as altered.

A permission-restricted PDF, one that opens without a password but limits actions such as printing or copying, gets Shisho's metadata too, and keeps its original encryption and permissions. Shisho cannot add its metadata to a PDF that needs a password to open or to one whose internal structure it cannot read, so these count as files whose contents Shisho cannot rewrite, and downloads of them fall back as described above.

KePub Generation

Shisho can generate Kobo-optimized KePub downloads from EPUB and CBZ only. M4B, PDF, MOBI, and AZW3 remain in their native formats. See Kobo Sync, eReader Browser, and OPDS Catalog for device delivery options.

Audiobook Browser Compatibility

Most M4B files use AAC-LC or HE-AAC and play in current browsers. xHE-AAC playback is more limited: use Safari or an iOS browser for Shisho's direct audio stream. Firefox cannot play xHE-AAC, and Chrome does not support it in this progressive-streaming setup. In a browser that cannot play the file, the player shows a warning suggesting Safari, though its controls stay available. If broad browser playback matters, encode audiobooks as AAC-LC or HE-AAC.