Skip to content

Flutter package to parse EPUB files (ebooks!), with support for Media Overlays! πŸ”‰πŸ“‘

License

Notifications You must be signed in to change notification settings

SofieTorch/epub_decoder

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

48 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“‘ EPUB Parser for Flutter πŸ“‘
Pub Version

Flutter Package to parse EPUB files (EBooks), with support for Media Overlays!

If you found this package useful, star this repo and drop a like in pub.dev! 🌟.

Features

βœ… Read EPUB from bytes
βœ… Read EPUB from dart:io file
βœ… List metadata: title, authors, language, etc. (with support for EPUB2)
βœ… List resources: audio, images, text, etc.
βœ… List sections (also commonly named "chapters") in default reading order
βœ… Get section audio (if exists)
βœ… Get text-audio synchronization info for each section
βœ… Get text segment given a time for each section

Work in progress

  • Read navigation definition
  • Support for bindings

Getting started

Install epub_decoder as a dependency.

Usage

Start by instancing an Epub from an Epub file:

import 'package:epub_decoder/epub_decoder.dart';

// Creating an EPUB from an asset transformed to bytes
final epubFile = await rootBundle.load('assets/example.epub');
final epub = Epub.fromBytes(epubFile.buffer.asUint8List());

And then, access its properties:

  • Main info: epub.title, epub.authors, epub.cover.

  • Retrieving Metadata: epub.metadata

    Expand for example result

    Please note that this is actually a List<Metadata> object (here you are seeing its .toString() representation).

    [
        {
            key: identifier,
            id: pubID,
            value: urn:uuid:8a5d2330-08d6-405b-a359-e6862b48ea4d,
            refinements: [
                {
                    id: null,
                    value: uuid,
                    refinesTo: pubID,
                    property: identifier-type,
                    schema: null,
                    name: null,
                    content: null,
                    refinements: []
                }
            ]
        },
        {
            key: title,
            id: title,
            value: [DEMO] How To Create EPUB 3 Read Aloud eBooks,
            refinements: []
        },
        {
            key: creator,
            id: aut,
            value: Alberto Pettarin,
            refinements: [
                {
                    id: null,
                    value: aut,
                    refinesTo: aut,
                    property: role,
                    schema: null,
                    name: null,
                    content: null,
                    refinements: []
                },
                {
                    id: null,
                    value: Pettarin, Alberto,
                    refinesTo: aut,
                    property: file-as,
                    schema: null,
                    name: null,
                    content: null,
                    refinements: []
                }
            ]
        },
        {
            id: null,
            value: portrait,
            refinesTo: null,
            property: rendition:orientation,
            schema: null,
            name: null, content: null, refinements: []
        },
        {
            id: null,
            value: 0:00:53.320,
            refinesTo: s001,
            property: media:duration,
            schema: null,
            name: null,
            content: null,
            refinements: []
        }
    ]
    
    
  • Retrieving resources/items: epub.items

    Expand for example result

    Please note that this is actually a List<Item> object (here you are seeing its .toString() representation).

    [
        {
            id: toc,
            href: Text/toc.xhtml,
            mediaType: ItemMediaType.xhtml,
            properties: [ItemProperty.nav],
            mediaOverlay: null,
            refinements: []
        },
        {
            id: cover,
            href: Text/cover.xhtml,
            mediaType: ItemMediaType.xhtml,
            properties: [],
            mediaOverlay: null,
            refinements: []
        },
        {
            id: c001,
            href: Styles/style.css,
            mediaType: ItemMediaType.css,
            properties: [],
            mediaOverlay: null,
            refinements: []
        },
        {
            id: p001,
            href: Text/p001.xhtml,
            mediaType: ItemMediaType.xhtml,
            properties: [],
            mediaOverlay: {
                id: s001,
                href: Text/p001.xhtml.smil,
                mediaType: ItemMediaType.mediaOverlay,
                properties: [],
                mediaOverlay: null,
                refinements: [{
                    id: null,
                    value: 0:00:53.320,
                    refinesTo: s001,
                    property: media:duration,
                    schema: null,
                    name: null,
                    content: null,
                    refinements: []
                }]
            },
            refinements: []
        }
    ]
    
    
  • Retrieving reading sections: epub.sections

    Expand for example result

    Please note that this is actually a List<Section> object (here you are seeing its .toString() representation).

    [
        {
            content: {
                id: cover,
                href: Text/cover.xhtml,
                mediaType: ItemMediaType.xhtml,
                properties: [],
                mediaOverlay: null,
                refinements: []
            },
            readingOrder: 1,
            audioDuration: null,
            smilParallels: []
        },
        {
            content: {
                id: p001,
                href: Text/p001.xhtml,
                mediaType: ItemMediaType.xhtml,
                properties: [],
                mediaOverlay: {
                    id: s001,
                    href: Text/p001.xhtml.smil,
                    mediaType: ItemMediaType.mediaOverlay,
                    properties: [],
                    mediaOverlay: null,
                    refinements: [{
                        id: null,
                        value: 0:00:53.320,
                        refinesTo: s001,
                        property: media:duration,
                        schema: null,
                        name: null,
                        content: null,
                        refinements: []
                    }]
                },
                refinements: []
            },
            readingOrder: 2,
            audioDuration: 0:00:53.320000,
            smilParallels: [
                {
                    id: p000001,
                    clipBegin: 0:00:00.000000,
                    clipEnd: 0:00:02.680000,
                    textFileName: p001.xhtml,
                    textId: f001
                },
                {
                    id: p000002,
                    clipBegin: 0:00:02.680000,
                    clipEnd: 0:00:05.480000,
                    textFileName: p001.xhtml,
                    textId: f002
                },
                {
                    id: p000003,
                    clipBegin: 0:00:05.480000,
                    clipEnd: 0:00:08.640000,
                    textFileName: p001.xhtml,
                    textId: f003
                },
                {
                    id: p000004,
                    clipBegin: 0:00:08.640000,
                    clipEnd: 0:00:11.960000,
                    textFileName: p001.xhtml,
                    textId: f004
                }
            ]
        }
    ]
    
    
  • Retrieving text segment from a certain time

    final section = epub.sections[1];
    final targetTime = Duration(seconds: 10);
    print(section.getParallelAtTime(targetTime)));
    Expand for example result

    Please note that this is actually a SmilParallel object (here you are seeing its .toString() representation).

    {
        id: p000004,
        clipBegin: 0:00:08.640000,
        clipEnd: 0:00:11.960000,
        textFileName: p001.xhtml,
        textId: f004
    }
    
    

Additional information

To understand EPUB3 specification and therefore plan the structure of this package, the following page was taken as reference: Package and Metadata | EPUB3 Best Practices.

However, you can learn more about in the EPUB3 official specification documentation and EPUB Media Overlays documentation.

Contributing

  • If you have any request or find some bug, feel free to open a new issue.
  • if you want to contribute, open a new issue with your proposal and if approved, continue with a pull request πŸ˜‰.

About

Flutter package to parse EPUB files (ebooks!), with support for Media Overlays! πŸ”‰πŸ“‘

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages