epub library

EPUB parsing entry points and EPUB-specific document contracts.

Classes

ArchiveEntry
A physical entry of a book's container archive.
BinaryFile
Represents a binary book file.
Book
A fully parsed book, independent of its source format.
BookCover
A book cover: raw bytes plus the detected image type.
BookFile
Abstract representation of a file inside a book container.
BookMetadata
Format-agnostic book metadata extracted from any supported book file.
BookStatistics
Basic reading statistics computed from book content.
DocumentBook
A document-backed book produced by text and office-format adapters.
Epub2Metadata
EPUB 2 metadata.
Epub2Package
EPUB 2 package document and its parsed components.
Epub3Metadata
EPUB 3 metadata, including accessibility and media-overlay fields.
Epub3Package
EPUB 3 package document and its parsed components.
EpubAccessibility
EPUB accessibility metadata declared in the OPF package document.
EpubBook
A parsed EPUB 2.0 / 3.0 book.
EpubDiagnostic
One structural EPUB finding with a stable rule identity.
EpubDiagnosticsOptions
Bounds applied while collecting diagnostics. They are report bounds, not safety boundaries: crossing one sets EpubDiagnosticsReport.truncated and keeps the collected findings. Container-level safety limits stay typed failures exactly as in reading.
EpubDiagnosticsReport
Deterministic structural report for one EPUB container.
EpubDocument
Domain contract for a parsed EPUB document.
EpubLandmark
A named destination in an EPUB 3 landmarks navigation section.
EpubMetadataUpdate
The metadata changes to apply to an EPUB file.
EpubPackage
Base representation of an EPUB package document.
EpubRendition
EPUB 3 display preferences from package metadata and spine properties.
EpubSpineRendition
Properties declared on a spine item, overriding publication preferences.
EpubViewport
Page dimensions declared for an EPUB content document.
Files
The files contained in a parsed book.
Guide
EPUB 2 guide containing references to publication sections.
Manifest
Resources declared by an EPUB package manifest.
ManifestItem
A resource declared by an EPUB manifest.
MediaOverlayDocument
A parsed SMIL overlay document: the flattened, ordered segments of one content document's narration.
Metadata
Metadata extracted from an EPUB package document.
The navigation (table of contents) of a book.
Represents a navigation point (table of contents entry) in a book.
OverlaySegment
One narrated fragment of an EPUB 3 media overlay: the audio clip plus the content-document element it narrates.
ReadingOrderItem
One entry of a book's reading order.
Reference
A section reference from an EPUB 2 guide.
Spine
The EPUB reading order and its page-flow direction.
TextFile
Represents a text book file.

Enums

BookFormat
The book formats supported by unseal.
EpubDiagnosticSeverity
Severity of an EPUB structural diagnostic.
EpubFlow
Preferred handling of content that overflows a viewport.
EpubLayout
How an EPUB content document is laid out.
EpubOrientation
Preferred display orientation declared by an EPUB.
EpubPageSpread
Placement of a spine item in a synthetic spread.
EpubSpread
Preferred synthetic spread behavior.
PageProgressionDirection
The page-flow direction of a book's spine: how a reading application should order the pages of a facing-page spread and which direction the "next page" gesture moves toward.

Functions

diagnoseEpub(Uint8List bytes, {EpubDiagnosticsOptions options = const EpubDiagnosticsOptions()}) → EpubDiagnosticsReport
Diagnoses EPUB bytes and returns a structural report.
diagnoseEpubArchive(Archive archive, {EpubDiagnosticsOptions options = const EpubDiagnosticsOptions()}) → EpubDiagnosticsReport
Diagnoses an already decoded EPUB archive.
findEpubRootFilePath(Archive epubArchive) → String?
Finds a usable OPF package path in epubArchive.
getEpubRootFilePath(Archive epubArchive) → String?
Retrieves the root file path of the EPUB from the provided archive.
parseEpubArchive(Archive archive, {String? rootFilePath}) → EpubBook
Parses an already decoded EPUB archive into an EpubBook.
parseEpubBook(Uint8List bytes) → EpubBook
Parses an EPUB from raw bytes.
parseMediaOverlay(String smilXml, {required String smilPath}) → MediaOverlayDocument
Parses a SMIL media overlay document (EPUB 3) into flattened, playback-ordered OverlaySegments.
parseSmilClock(String? value) → Duration?
Parses a SMIL clock value into a Duration. Supported forms per the SMIL/EPUB spec: full clock (hh:mm:ss.fraction), partial clock (mm:ss.fraction), timecount with unit (12.5s, 450ms, 2min, 1h) and bare numbers (seconds). Returns null for empty or unparseable values.
readEpubMetadata(Archive archive, {String? rootFilePath}) → BookMetadata
Reads only the metadata of an EPUB archive.
updateEpubMetadata(Uint8List bytes, EpubMetadataUpdate update) → Uint8List
Rewrites the OPF of the EPUB in bytes with update applied and returns the new EPUB bytes.

Exceptions / Errors

DrmProtectedException
Thrown when a book is protected by DRM and cannot be parsed.
EmptyBytesException
Exception thrown when an EPUB parser receives no bytes.
EpubException
Error thrown while reading or parsing an EPUB document.
FormatNotSupportedException
Thrown when the book format is recognized but not supported by Unseal.
InvalidBookException
Thrown when the underlying data cannot be parsed as the detected format.
UnsealException
Base class for all exceptions thrown by Unseal.