flutter_readium

Build EPUB, PDF, audiobook, comic, and WebPub readers in Flutter with one unified Dart API—powered by Readium toolkits on iOS, Android, and Web.

Get started · Example app · API docs

Captured on iOS: EPUB styling, read-along, then narrated comic panels.

Features Read EPUB 2/3 and WebPub with pagination, scrolling, themes, and typography controls. Open PDFs on iOS and Android, plus CBZ and DiViNa comics. Play audiobooks with track navigation and variable speed. Follow Media Overlay read-along highlighting and page-level narrated comic navigation. Listen with text-to-speech, including voice, speed, and pitch controls where available. Highlight and annotate text, search on iOS and Android, and restore reading position. Use one Dart API for reader and playback events, with custom HTTP headers.

Select an iOS Simulator capture to see it full size.

EPUB themes	Read-along	Narrated comics

EPUB highlights	PDF pages

Add the package:

flutter pub add flutter_readium

See the complete reader screen for opening a local file or URL, mounting the reader, and closing the publication. The five-minute walkthrough continues with navigation, preferences, and position restoration.

flutter_readium is a federated plugin that delegates to the upstream Readium toolkit on each platform:

• swift-toolkit 3.11.0 on iOS
• kotlin-toolkit 3.3.0 on Android
• ts-toolkit (@readium/shared, @readium/navigator) on Web

The canonical version pins live in flutter_readium/ios/flutter_readium.podspec, flutter_readium/android/build.gradle (ext.readium_version), and flutter_readium/package.json. Run bin/readium_versions to print them at any time.

¹ DiViNa audio narration is driven by a Guided Navigation document and synchronizes at the page level on all platforms (on Web, ts-toolkit has no DiViNa navigator, so images are rendered by a plugin-side navigator). Panel-level zoom (the segments' xywh regions) is not yet implemented on any platform.

LCP-protected publications are not currently supported. The underlying toolkits include an LCP adapter; it may be enabled in a future release.

¹ Web TTS uses the browser's Web Speech API — voice availability and quality vary by browser.

macOS note: Native macOS desktop (flutter run -d macos) is not supported — a no-op stub is registered so the Flutter macOS target still compiles, but every reader call returns MethodNotImplemented. The upstream swift-toolkit is iOS-only and has marked native macOS not_planned. The iOS build runs fine on Apple Silicon Macs via "Designed for iPad".

The development SDK is pinned separately in .flutter-version; contributors should use bin/update_flutter_version to change that pin.

Complete the per-platform setup below before running the reader. See the full installation guide for details.

• Set minSdkVersion to 24 or higher in android/app/build.gradle.

• Enable core library desugaring — the readium-kotlin-toolkit artifacts require it, and the build fails at checkDebugAarMetadata without it:

  android {
      compileOptions {
          isCoreLibraryDesugaringEnabled = true
      }
  }
  
  dependencies {
      coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
  }

• Change your MainActivity to extend FlutterFragmentActivity (not FlutterActivity) — otherwise the reader view will crash at runtime.

• If using TTS or background audio, add to android/app/src/main/AndroidManifest.xml:

  <uses-permission android:name="android.permission.WAKE_LOCK" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

The Android plugin exposes the following Gradle properties. Set them in your app's android/gradle.properties to override the defaults at build time:

Example android/gradle.properties:

flutterReadium.mediaOverlayFetchConcurrency=16

Add the Readium pods to your ios/Podfile.

To avoid documentation drift, copy the exact Readium pod lines from:

• flutter_readium/example/ios/Podfile (source-of-truth for app integration)
• and keep them aligned with flutter_readium/ios/flutter_readium.podspec (plugin-side pin)

Example shape:

target 'Runner' do
  use_frameworks!
  use_modular_headers!
  # Readium pod lines: copy from flutter_readium/example/ios/Podfile
  # ...
end

1. Copy the plugin's JavaScript bundle into your web app:

   dart run flutter_readium:copy_js_file <destination_directory>

   The destination should live inside your web/ directory.

2. Reference the script from web/index.html:

   <script src="flutter.js" defer></script>
   <script src="readiumReader.js" defer></script>

Full documentation is in docs/:

• Getting Started
  • Installation
  • Quick Start
  • Core Concepts
• Guides
  • EPUB Reading
  • Audiobook Playback
  • Text-to-Speech
  • Preferences
  • Highlights & Annotations
  • Search
  • Custom HTTP Headers
  • Saving Progress
  • Error Handling
• API Reference
  • FlutterReadium class
  • ReaderWidget
  • Locator
  • Preferences
  • Decorations
  • Streams & Events
  • Error Codes
  • Publication
• Architecture — Overview
• Troubleshooting — Troubleshooting

A complete example app is available in flutter_readium/example/, demonstrating EPUB and audiobook reading, TTS, preferences, and highlighting:

cd flutter_readium/example && flutter run

The README animation and capability screenshots are driven by a small integration-test-style showcase recorded from a booted iOS Simulator. Once the generated test fixtures are installed, regenerate them with:

bin/generate_readme_demo [--no-bezel] [--device-id <simulator-udid>]

The physical device bezel is included by default. The script keeps the H.264 master under build/readme-demo/ and replaces the checked-in media only after the capture and size checks pass.

• helper scripts: cd flutter_readium/assets/_helper_scripts && npm run build:stats (outputs flutter_readium/assets/helpers/stats.html and flutter_readium/assets/helpers/stats.json)
• web bundle: cd flutter_readium && npm run build:stats (outputs flutter_readium/build/rollup-stats.html and flutter_readium/build/rollup-stats.json)

See CONTRIBUTING.md for development setup, build scripts, and contribution guidelines.

BSD 3-Clause — see LICENSE.