API Reference

📚 ebook-rs Complete API Reference & Parity Guide (v0.8.0)

This document provides complete API documentation for ebook-rs (v0.8.0), bifurcated into Drop-in Replacements for epub.js and ebook-rs Native Extensions.

---

🟢 Section A: Drop-in Replacement for epub.js APIs

These ebook-rs APIs match the concepts, structures, and behavior of epub.js (e.g. ePub(url), book.loaded.*, rendition.display(), rendition.annotations), enabling web developers and Rust engineers to migrate seamlessly.

epub.js Feature / API	🚀 ebook-rs Equivalent API	Description
ePub(url) / ePub(buffer)	Book::from_file(path) / Book::from_bytes(bytes)	Loads and parses package files into an in-memory Book struct.
book.loaded.metadata	book.metadata()	Returns Metadata containing title, creators, publishers, languages, pub_date, etc.
book.loaded.spine	book.spine()	Returns Vec<SpineItem> containing ordered chapter items (idref, href, linear).
book.loaded.navigation.toc	book.toc()	Returns Vec<NavPoint> hierarchical Table of Contents points.
book.loaded.navigation.landmarks	book.landmarks()	Returns Vec<Landmark> (cover, titlepage, bodymatter).
book.loaded.navigation.pageList	book.page_list()	Returns Vec<PageListItem> printed page numbers.
book.locations.generate()	book.generate_locations(chunk_size)	Generates discrete location progress markers across chapters.
book.locations.percentageFromCfi()	book.locations.percentage_from_location(loc)	Converts location integer indices to decimal progress percentage (0.0 .. 1.0).
rendition.display(cfi)	book.get_section(spine_idx) / Cfi::parse()	Retrieves raw and processed HTML content at specified CFI location.
rendition.annotations.add()	book.annotations.create_highlight() / to_w3c_json()	Creates highlights and exports W3C Web Annotation JSON-LD format.

---

🔵 Section B: ebook-rs Native Extensions (Beyond epub.js)

Where ebook-rs extends far beyond epub.js to provide native multi-format support, zero-alloc searching, font de-obfuscation, EPUB 3 Accessibility, SMIL Media Overlays, Readium LCP/Locators, Regex Search, EPUB Validation, Fingerprinting, and Citation Export.

1. Multi-Format Native Parsers (MobiBook, Fb2Book, LitBook, CbzBook, PdfBook, OdtBook, TxtBook)

epub.js only supports .epub files. ebook-rs natively supports EPUB 2/3, MOBI, AZW3, FB2, KEPUB, LIT, CBZ, PDF, ODT, TXT, and Markdown files out of the box.

2. EPUB 3 Accessibility Metadata (AccessibilityMetadata)

EPUB 3 Accessibility 1.1 & Schema.org metadata parsing:

let a11y = &book.metadata().accessibility;
println!("Access Modes: {:?}", a11y.access_modes);
println!("Summary: {:?}", a11y.accessibility_summary);
assert!(a11y.is_screen_reader_friendly());

3. EPUB 3 Media Overlays (SMIL Sync) (MediaOverlayPackage)

Synchronized audio-text read-aloud overlays (.smil):

for (smil_path, pkg) in &book.media_overlays {
    if let Some(text_ref) = pkg.find_text_ref_by_timestamp("ch1.mp3", 8.5) {
        println!("Active element ID: {:?}", text_ref.element_id);
    }
}

4. Readium LCP DRM, Unified Locators & Search API

• LCP DRM: LcpLicense::parse() & LcpDecryptor::decrypt_bytes()
• Unified Locators: book.to_readium_locator(spine_idx, char_offset)
• Search API: SearchEngine::to_readium_search_json(&results, query)

5. Regex Full-Text Search Engine

let matches = book.search_regex("(?i)quantum|physics")?;

6. EPUB Structural Validator (EpubValidator)

let report = book.validate();
println!("Is Valid: {}, Errors: {}", report.is_valid, report.errors_count);

7. Content Fingerprinting & Deduplication (BookFingerprint)

let fp = book.fingerprint();
let match_score = fp.match_score(&other_fp);

8. Academic Citation Exporter (CitationExporter)

println!("BibTeX:\n{}", book.to_bibtex());
println!("APA: {}", book.to_apa());
println!("MLA: {}", book.to_mla());
println!("Chicago: {}", book.to_chicago());

9. Tree-sitter Concrete Syntax Tree Engine (TreeSitterEngine)

let code_blocks = book.extract_code_blocks();
for block in code_blocks {
    println!("Lang: {}, AST Nodes: {}", block.language, block.ast_nodes.len());
}

10. Synthetic FXL 2-Page Spreads (SyntheticSpread)

let spread = book.get_synthetic_spread(0, Some(1))?;
println!("Spread HTML: {}", spread.combined_html);

11. Table of Contents Deep Search & Flattening (NavPoint::search, NavPoint::flatten)

let matches = book.search_toc("quantum");
let flat_toc = book.flatten_toc();

12. Universal EPUB 3 Exporter (export_epub3_bytes())

let epub_bytes = book.export_epub3_bytes()?;
std::fs::write("converted.epub", epub_bytes)?;

13. Zero-Copy Memory-Mapped I/O (Book::from_mmap)

let book = Book::from_mmap("omnibus.cbz")?;

14. Lightweight DOM AST Tree (EbookDomTree, DomNode)

let mut tree = EbookDomTree::parse("<div><script>alert(1)</script><p>Text</p></div>");
tree.strip_elements(&["script"]);
let clean = tree.to_html();

15. Legacy Non-UTF-8 Charset Decoding (decode_bytes_with_encoding)

let decoded = decode_bytes_with_encoding(bytes, Some("windows-1252"));

16. Automatic Language Detection (book.detect_language())

let lang = book.detect_language(); // Some("eng")

17. Zstd Compressed State Caching (export_zstd_cache, from_zstd_cache)

let cache_bytes = book.export_zstd_cache()?;
let restored = Book::from_zstd_cache(&cache_bytes)?;

18. SpeechSynthesis TTS Word Synchronizer (TtsWordToken, get_tts_tokens)

let tokens = book.get_tts_tokens(0)?;
let html = book.get_tts_section_html(0)?;