Skip to content

flutter-readium.md

Latest commit

 

History

History
103 lines (79 loc) · 5.64 KB

flutter-readium.md

File metadata and controls

103 lines (79 loc) · 5.64 KB
Raw

FlutterReadium class

FlutterReadium is a singleton that provides the full reader API. Obtain the instance with FlutterReadium().

Publication lifecycle

Method Description
loadPublication(url) Parse a publication manifest without opening it for reading. Never affects the open publication.
openPublication(url) Open a publication for reading; required before showing [ReadiumReaderWidget] or using any navigation API. ⚠️ Only one publication can be open at a time. Opening the URL that is already open returns that publication without reloading it; call closePublication() first to reload.
closePublication() Close the current publication and release native resources 
final pub = await FlutterReadium().openPublication(url);
// ...
await FlutterReadium().closePublication();

Navigation

Method Description
goForward() Next page or section
goBackward() Previous page or section
goToLocator(locator) Navigate to an exact position; returns true on success
goToProgression(value) Navigate to a 0.0–1.0 position in the current resource
goByLink(link, pub) Navigate to a publication link
toPhysicalPageIndex(index, pub) Navigate to a printed page number. TODO: will be deprecated in favor of goByLink
skipToNextTOC(publication, currentTocHref) Skip to next chapter
skipToPreviousTOC(publication, currentTocHref) Skip to previous chapter

Preferences

Method Description
setDefaultPreferences(prefs) Set EPUB defaults applied to all future publications. See preferences.md
setDefaultPDFPreferences(prefs) Set PDF defaults applied to every PDF opened afterwards. setPDFPreferences also updates them. See preferences.md
setEPUBPreferences(prefs) Apply EPUB display preferences to the current publication. See preferences.md
setPDFPreferences(prefs) Apply PDF display preferences to the current publication and update the PDF defaults. See preferences.md
setCustomHeaders(headers) Set HTTP headers used for all network requests
setLogLevel(level) Set the plugin's internal log verbosity
setAudioRecoveryPolicy(policy) Configure audio-stream error recovery and resource-loading watchdog reporting/recovery. See error-codes.md

Decorations

// Apply (or replace) a named group
await FlutterReadium().applyDecorations('highlights', decorations);

// Clear a group
await FlutterReadium().applyDecorations('highlights', []);

TTS

Method Description
ttsEnable(prefs) Enable TTS for the current publication. See preferences.md
ttsSetPreferences(prefs) Update TTS preferences without restarting. See preferences.md
ttsGetAvailableVoices() List all available voices
ttsSetVoice(id, language) Set a specific voice; language scopes it to a content language
setDecorationStyle(utterance, range) Set decoration styles for TTS highlighting

Available voices include the platform identifier, name, language, network status, gender and quality. When Readium Speech recognizes a voice, it provides a friendly label. Platform-reported male or female gender is preserved; a missing, null, or unspecified gender uses catalog gender when available, otherwise it remains unspecified. Platform-reported quality is preserved; when missing, it falls back to the highest quality listed by Readium Speech, which may describe a different variant. label is null when no match is found. Readium Speech veryHigh maps to TTSVoiceQuality.highest.

TODO: Slightly inconsistent that audioEnable takes a fromLocator and ttsEnable doesn't.

Audio

Method Description
audioEnable(prefs, fromLocator) Enable audio playback. See preferences.md
audioSetPreferences(prefs) Update audio preferences. See preferences.md
audioSeekBy(offset) Seek by a Duration offset rounded to whole seconds (positive = forwards, negative = backwards)

Shared playback controls

Used by both TTS and audio modes:

await reader.play(locator);   // null = current position
await reader.pause();
await reader.resume();
await reader.stop();
await reader.next();
await reader.previous();

Search

final results = await FlutterReadium().searchInPublication('query');

Event streams

Stream Type Description
onReaderStatusChanged ReadiumReaderStatus Loading, ready, closed, error. See enums.dart
onTextLocatorChanged Locator Visual reader position changes. See locator.md
onTimebasedPlayerStateChanged ReadiumTimebasedState Audio/TTS playback state. See timebased_state.dart
onExternalPlaybackCommand ReadiumExternalPlaybackCommand System media-control commands such as headphones / Control Center play and pause. See external_playback_command.dart
onErrorEvent ReadiumError Non-fatal errors. See readium_exceptions.dart