README.md (8576 bytes)
1 # SubRead read-along for KOReader 2 3 A KOReader plugin that makes the book follow an audiobook narration. 4 5 [SubRead](https://subread.space) makes a subtitle file (`.srt`) for an 6 audiobook. The cue text is the text of the ebook itself. The cue times are the 7 times when the narrator reads each line. KOReader has no audio player, so you 8 play the audiobook in another app, on your phone or on the same device. This 9 plugin runs a clock with that player, turns the pages of the book for you, and 10 marks the line that the narrator reads. 11 12 ## Install 13 14 1. Copy the whole `subread.koplugin` folder into the `plugins` folder of your 15 KOReader installation: 16 17 ``` 18 koreader/plugins/subread.koplugin/ 19 ``` 20 21 2. Restart KOReader. 22 3. Open a book. The plugin is in the reader menu, under **Tools → 23 SubRead read-along**. 24 25 ## Make the subtitle file 26 27 1. Go to <https://subread.space> (there is also an Android app). 28 2. Give it the audiobook and the ebook. 29 3. Save the `.srt` file it makes. 30 31 Put the file beside the book file and give it the same name: 32 33 ``` 34 Dracula.epub 35 Dracula.srt <- found by itself 36 Dracula.en.srt <- also found by itself 37 ``` 38 39 If the file is somewhere else, open **Tools → SubRead read-along** and tap the 40 first line to select it with the file browser. The plugin remembers the choice 41 for that book. 42 43 ## Use it on Android, with the audio player 44 45 On Android the plugin reads the position of the audio player, so the book 46 follows the audio exactly. KOReader has no notification access, so it cannot 47 see the player itself. The [SubRead Overlay](https://github.com/equwal/subread-overlay) 48 app has that access and answers for KOReader. 49 50 1. Install SubRead Overlay and give it notification access. Its panel does 51 not need to be on the screen. 52 2. Start the audiobook in your audio player (Voice, VLC, Smart AudioBook 53 Player, or any player with a media session). 54 3. In KOReader, open **Tools → SubRead read-along → Start read-along**. 55 4. The plugin reads the player every two seconds and turns the pages with it. 56 Start, Pause, the seeks and **Move the audio to this page** control the 57 player. 58 59 A dictionary lookup pauses the player. It plays again when you close the 60 lookup window, or when you come back from an external dictionary app. 61 62 **Follow the audio player** in the menu turns this off. The plugin then runs 63 its own clock, as below. 64 65 ## Use it with the own clock 66 67 Without SubRead Overlay, or on a device that is not Android, the plugin runs 68 a clock beside your player. 69 70 1. Start the audiobook in your audio player. 71 2. In KOReader, open **Tools → SubRead read-along → Start read-along**. 72 3. The clock starts at the time of the first cue on the page you are reading, 73 or at the position you had last time. 74 4. Use **Sync the clock to this page**, or select the words the narrator is 75 reading and choose **SubRead: sync here**, to set the clock exactly. 76 77 ### Controls 78 79 The controls dialog shows the position, whether the audio plays, and the cue 80 that is on. 81 82 | Control | What it does | 83 |---|---| 84 | Prev. cue / Next cue | Back or forward one cue | 85 | `-10 s` / `+10 s` | Back or forward ten seconds | 86 | Start / Pause | Starts or stops the player, or the own clock | 87 | Stop | Stops the follow and takes the mark off | 88 | Move the audio to this page | Seeks the player to the first cue on the page. With the own clock: sets the clock there. | 89 | Go to time… | Seeks to a position you type | 90 | Speed | 0.5 to 3.0, for the own clock. The player reports its own speed. | 91 | Offset | Seconds to add to the subtitle times. Use a positive value when the audio file starts with an intro that is not in the book. | 92 | Mark | How the line is marked: Shade, Underline, Strikeout, Invert or None. Each tap sets the next one. | 93 | What time is this page? | Shows the time of the first cue on the page | 94 95 Select text in the book and use **SubRead: sync here** to move the audio, or 96 the clock, to the cue that holds those words. 97 98 The clock position, the speed and the offset are kept for each book. 99 100 ### Gestures and keys 101 102 The plugin adds three actions to the gesture manager and the key bindings: 103 104 * SubRead: controls 105 * SubRead: start or pause 106 * SubRead: sync to this page 107 108 ## How it finds the place 109 110 The plugin does not read the whole book for every cue. It takes the first few 111 words of the cue and searches forward from the page you are on, the same 112 search that KOReader's own full text search uses. A hit before the nearest cue 113 already found is dropped, and so is a hit many pages after it: the same words 114 at another place of the book must not pull the follow away. Found places are 115 kept for the session. 116 117 When a cue is not found after the page you are on, the plugin reads the 118 whole book once, with the place of the nearest cue it already found as the 119 lower limit. This is what happens after a jump in the audio, or after you 120 turned pages away from the narration. When the cue is not in the book at 121 all, the plugin keeps the last place and waits a few cues before it searches 122 again. The wait doubles with each miss, up to four cues. This keeps the cost 123 low when a stretch of the book is missing from the subtitle file. 124 125 A cue whose text starts with `＊` has no place in the book. The plugin leaves 126 the view alone for such a cue. 127 128 ## E-ink 129 130 The screen is only redrawn when the cue changes. A timer tick on its own never 131 redraws anything. A mark that moves inside the same page uses the light `ui` 132 refresh. A page turn uses the `partial` refresh. 133 134 The mark is drawn over the page with the same line boxes and the same shade 135 that KOReader uses for a highlight. It is never written into your 136 highlights. 137 138 ## Limits 139 140 * Only EPUB, FB2, TXT and HTML books work. PDF and DjVu have no xpointer, so 141 the place cannot be followed. The plugin says so and does nothing. 142 * The white space of the cue text and of the book text can differ. The search 143 folds white space, so this is not a problem. 144 * Ruby text (furigana, `<rt>`) is not in the cue text. The plugin searches for 145 a short piece of the cue, so a line with ruby usually still matches. A line 146 that does not match is skipped and the last place stays. 147 * "What time is this page?" needs a next page, so it does not work on the last 148 page of the book. 149 * Without SubRead Overlay the plugin cannot see or control your audio player. 150 It only follows its own clock. 151 152 ## Tests 153 154 The logic that does not need KOReader is in `subread/`. The tests are in 155 `spec/`. 156 157 With busted: 158 159 ``` 160 busted 161 ``` 162 163 Without a Lua interpreter with busted: 164 165 ``` 166 lua spec/run.lua 167 ``` 168 169 ## More projects 170 171 - [SubRead](https://subread.space/): read along with an audiobook, in the browser. 172 Also [for Android](https://github.com/equwal/subread-android/releases/latest), 173 [for YouTube](https://github.com/equwal/subread-extension/releases/latest) 174 and [for KOReader](https://github.com/equwal/subread.koplugin). 175 - [SubRead Overlay](https://github.com/equwal/subread-overlay/releases/latest): subtitle lines over any Android media player. 176 - [SubRead Dictionary](https://github.com/equwal/subread-dictionary/releases/latest): a pop-up dictionary for Android that reads Yomitan dictionaries. 177 - [SubRead Anki](https://github.com/equwal/subread-anki): one tap makes an Anki card from any Android app. 178 - [Subrep](https://github.com/equwal/subrep-android/releases/latest): live captions of the sound of your phone. 179 - [Book Simulator](https://booksimulator.com/): a reading room for Aozora Bunko and Project Gutenberg books. 180 - [honjimaku.com](https://honjimaku.com/): subtitles for Japanese audiobooks. 181 - [sbm Sync](https://sbmsync.com/): your bookmarks, the same on every device, 182 with [sbm](https://github.com/equwal/sbm) for dmenu, 183 [sbm for Android](https://github.com/equwal/sbm-android/releases/latest) 184 and the [sbm add-on](https://github.com/equwal/sbm-extension/releases/latest) for Firefox and Chrome. 185 - [Rebind](https://github.com/equwal/rebind/releases): remap the hardware buttons of e-ink readers and Android, 186 with [Ink Recents](https://github.com/equwal/ink-recents/releases/latest), 187 [Ink Dim](https://github.com/equwal/ink-dim/releases/latest) 188 and [Ink Update](https://github.com/equwal/ink-update/releases/latest). 189 - [dickt.store](https://dickt.store/): language-learning tools, flashcards and web toys. 190 - [hentaibun.online](https://hentaibun.online/): learn kanbun and kobun. 191 - [Recently Written](https://recentlywritten.com/): the blog, and a list of [all projects](https://recentlywritten.com/projects.html). 192 193 ## License 194 195 AGPL-3.0-or-later. See `LICENSE`. KOReader is AGPL-3.0, and this plugin is 196 loaded into it.