Interactive annotation viewer/exporter for PocketBook e-readers, with additional tools.
We do:
We don’t:
Some highlights
PocketBook readers, with recent 6.x firmware.
Older firmware versions (5.x) are likely only partially supported - we are open to feedback.
Loading annotations directly from a device takes longer due to their slower storage mediums: the ‘local mirror’ feature improves this. See also performance improvements.
In general, performance is expected to be good to acceptable even on older hardware. As of v0.9.7, on Windows annotation loading and display speeds have been vastly improved. Further optimizations are available under “Settings > Annotation Viewer”.
The data directory [C] may be synced across devices. The generic settings [A] are then configured locally, but this can be overridden using the CLI. However, these settings are few and easily reproduced.
Option (4) is the default situation. Any earlier condition takes precedence / overrides the default.
1. Portable mode (See below and "CLI Options")
2. CLI provided locations
3. GUI configured data location (settings dialog)
4. Default locations (Qt derived) if not provided by (2) and (3)Stores all settings and files in the application directory ‘<APP_DIR>’:
- avater.conf: <APPDIR>/avater.conf
- data: <APPDIR>/data/
- devices.conf: <APP_DIR>/data/devices.confShow available options.
Run application in portable mode.
Note: To convert a default ‘data’ directory for use with portable: copy/move it into the application directory. See also Settings and files.
Overrides the location of the generic avater.conf file.
Overrides the location of both the default/user-set data directory, and the therein stored devices.conf file.
Enable debug logging. The log is accessible under the help menu. Alternatively, enable this under “settings > advanced”.
Scans system for new or removed devices. This includes:
Both USB devices, and local mirrors (0.9.8+) are removed if not found (removed from the program, not unmounted; for local mirrors no files are removed).
If created, opens the ‘data’ directory using the OS’ file browser. See configuration files. Note: After the first startup, this directory may not yet exist.
Opens the settings dialog. (yet undocumented, but hovering over labels/options will show ‘tooltip’ pop-ups with information)
Removes all USB devices from the program - but does not unmount these from the OS.
If multiple annotation profiles exist, these are shown here. Changing profiles in the GUI is not yet implemented (but trivial to implement).
Scans system for new or removed devices. See also Rescan Devices
Removes the device from the program. This does not unmount the device.
If the device has a ‘local db mirror’, the device entry is kept, is labeled as disconnected, and any references to the device are purged. Ejecting ‘local mirrors’ does nothing.
Select one of multiple devices or locally mirrored devices.
Connected devices are indicated by addition of an e-reader icon, and a “connected” text-label. Entries without these are so-called local mirrors.
Switching between devices loads the annotations for the selected device (unless disabled under settings > Annotationsviewer). Previously loaded annotations are kept in memory until the device is removed from the program (for local DB mirrors this will not occur).
You may add a custom label using “Device Tools > Set Devicelabel”. For example the model type.
Available tools may differ per device and vendor.
This tool copies system files, such as apps and fonts, to their appropriate folders on the reader memory (or card memory).
It’s mainly intended for (partially) restoring backups generated by the program.
- .acsm (adobe digital download file)
- .app
- .dic (dictionary)
- .pbi (dictionary/app)
- .ttf (font)
- .otf (font)
- .ttc (font)
- .bin (update file)Files stored in .zip files, such as backup archives, can be processed and -if supported- extracted by the program.
Note that marking such a file for deletion, will delete the parent archive, not the individual file.
Not implemented yet. ACSM downloading is a planned feature.
Creates a common .zip backup archive with selected device content.
Type of files to backup:
Databases: Copies the (e-book) metadata and annotation database(s).
Note that databases are always archived, to prevent recovery problems at a later date.
Apps, Fonts, Dictionaries: No special remarks apply.
Other files (main/card): Copies any other files, excluding a) the previously discussed types and b) the /system/ folder. Also consider using a syncing tool or library manager instead. Note e-Reader transfer speeds tend to be slow (about 1-2 minutes per Gb)
e-Books and dictionary files tend to be already (maximally) compressed. As such, these are simply ‘stored’ in the .zip archive, saving (processing) time.
Ideally the end-user (you) would tests back-ups, which is not practical. The program employs some precautions to ensure correct storage, and will (attempt to) warn on failure.
Regarding data integrity: the .zip format’s internal checksums can (only) indicate data corruption after storage or transmission. Depending on the value of your data, consider a good backup strategy, and hardware/software integrity features (ECC, ZFS, etc.).
This tool checks both device and locally mirrored databases (DBs) for errors. It utilizes SQLite’s “integrity_check” feature in part.
Should any errors be indicated, click on “Show Details” for more information. Warnings regarding so-called ‘WAL’ files, or “database not found” are quite harmless; any other errors types can indicate serious issues, usually implying that DB is unrecoverable. However, you may still attempt to recover part or whole of the DB using third party recovery tools (SQLite’s CLI tool offers some free options). Success cannot be guaranteed, and as such, we do not offer a recovery tool.
Note: ‘WAL file’ related errors may be ignored, and may not persist across checks. Errors relating to opening databases may occur when the device monitor is disabled (by user or a failure to start), and a device was disconnected.
This allows merging of bookmarks/annotations for similar e-books.
After an e-book file is changed on the device, it may be treated as a new book. Examples are re-downloading encrypted public library e-books. Afterwards, annotations from the previous file may no longer show for the ‘new’ file.
This tool searches for such duplicated titles, and (interactively) modifies associated annotations to point to the (highest) ID representing the ‘newest’ book entry.
If you are sure the child items refer to the same book (see warnings), you may check these. Clicking the parent checks all child items. Next, click ‘Ok’ to apply the merge/fix.
Warning:
Please backup your database file(s) first, for example using the ‘Manual backup’ menu option.
The assumption is that the book content has not changed between each version. If it has, transferred annotations may point to the wrong locations, as the tool does not correct for this (yet).
Note: The PB database design tends towards adding or duplicating entries instead of modifying them. However, to avoid excessive duplication, this tool modifies data in-place.
Mirrors a device its databases locally, for accessing annotations when a device is disconnected.
If enabled for a device, the local mirror is updated whenever that device connects to the program. Annotations are then reloaded (or manually using “Reload annotations”).
This is a basic local caching solution, that leverages existing device support. A future centralized database is being considered.
Beware that a device reset (which resets the device DBs) will be carried over into the local mirror, thus erasing any previously locally stored annotations. Should you want to reset a device, store a manual backup before resetting. This backup can be imported to keep access to the annotations.
The label provided here, will be shown in the device selector.
Only visible when auto-loading annotations is disabled (see settings). If your device is slow, this may improve startup time.
The viewer displays annotation (meta)data in multiple columns.
Can be toggled by right-clicking in the ‘header’ bar (i.e. with “Title”, “Page”). By default, the “Date” and “Authors” columns are hidden.
Double clicking on the highlight or notes cell, allows selection and copying of text fragments. Note: Newlines are currently not shown.
Highlight colors can be shown (since 0.9.8), with an optional color text abbreviation. See Additional options..
Future AVATeR versions intend to allow editing of each annotation’s highlight color.
The viewer context menu (right-click), offer short-cuts for filtering on that row’s fields.
Copy this cell copies the pointed to cell’s content to the clipboard as raw text. For advanced export features, see the exporting section.
Copy selected row(s): short-cut for copy to clipboard. Follows the GUI sorting mode; for advanced export features, see the exporting section.
Selecting text segments If wanting to select text segments within a highlight/note, double click that cell to access the text. (Note: rich text formatting is to be implemented)
Clear Filters and show this row Clears all filters, and attempts to move the display to show this row, or the first selected one.
Allows interactive searching. Text searches are delayed, to reduce CPU usage. The duration can be changed under “settings > Annotation Viewer”.
Case sensitivity can be toggled under the Viewer Tools menu (right-most button).
Currently implemented only for “Search highlights/notes”. A general grasp of ‘common’ regular expression syntax will be beneficial. Some examples:
Note: This is still a basic feature. If you have a specific use-case, feel free to inform the authors.
The following sorting modes are available:
Note: Custom sorting is partially implemented, and does not persist across restarts.
Case sensitivity can be toggled under the Annotation Viewer menu.
Lastly, sorting of exported annotations can be configured separately.
Accessible via the right-most tools button.
Show notes inline: ‘Inlines’ note texts, hiding the note column. This should carry over into the note export.
Show Bookmarks: These are hidden by default. Only really useful for PDF files.
Row color mode Sets the highlight color mode. Options include full row coloring (default), the ‘color column’ or disabled. Note: May require scrolling to update the view
Toggle color text: Shows or hides a text abbreviation of the highlight color, for use in bad light conditions, with UI ‘nightlight’ modes or for visually impaired users. Note: May require scrolling to update the view
Resize Rows: Recomputes the row heights to show (nearly) all text. Should only be needed after resizing columns.
Reload Annotations: Reloads only the (annotation) data, and prompts the viewer to update. Normally not needed.
Reset Viewer: Resets both the viewer model, and reloads annotations. Normally not needed.
Selected annotations can be exported to file or the clipboard, using the buttons “To File…” or “To Clipboard” (in the bottom export toolbar). A short-cut is available via the context-menu (right-click on a viewer annotation row).
Export format
Export sorting mode By default, exports use the GUI sorting order. This can be overridden by selecting a sorting mode in the bottom export toolbar.
Export to “Clipboard” Copies selected annotation data to the clipboard.
Export “to file…” Opens a file dialog for selecting an export file, and exports selected annotations to that file.
Note: ‘note inlining’ should be carried over into the note export. This may become optional in the future.
Notes, PocketBooks: Highlights edited on PB devices using that device’s Notes app, may lose their page and highlight location data.
Reader disconnection during running/pending operations Disconnection will not (yet) cancel running operations - but tools are designed to avoid crashes due to removed resources. Generally some warning will be shown; file transfers and DB access tend to fail gracefully.
Connecting many readers at once Connecting multiple (supported) readers at once is still untested. Windows versions older than 0.9.8. perform a full device scan upon USB changes, and is not recommended.
If you can help test this, please contact the author(s). For extra safety, first disable “loading annotations” (under settings), restart the program, and then try (this avoids database access).
Minor issues:
Scroll CPU spikes Mouse-scrolling annotations can show up as a CPU load spike in visual CPU tools; in so far true, the used CPU time (i.e. duration) is very short.
Toggling sort case-sensitivity Sorting columns using the table header, ignores the case-sensitivity toggle. The sort by “title/date” and “title/page” modes do respect this setting. If not, switch between sort modes to apply changes.
Book metadata on PocketBooks For the time being, book metadata is read from the books.db file in order to keep things fast and simple. Other apps that change metadata may only target the explorer.db, explaining any discrepancies. With the v0.9.7 annotation loading improvements, matching books to explorer.db metadata has become practical.
Improve performance Since v0.9.7, the program was optimized for speed. If hard-pressed for speed, these changes will improve the situation:
use a local database mirror
use a filter preset of 6 months or less. This reduces the annotation display count. The setting is retained between restarts.
increase the search delay to 1000ms or more, removing interim searches
disable case-sensitive sorting, and prefer “sort on date”
Keep bookmarks hidden
Ensure the last (right-most) column is not stretched. If it is, right-click in the annotation viewer header, and select “reset columns”.
First, ensure the reader files are accessible from the OS (i.e. is mounted). Otherwise, the program will (silently) ignore the e-reader. For example, some Linux distributions will show but only mount filesystems upon user (UI) action.
Ensure your device is supported by this program. Also, newly introduced devices may use a new (USB) vendor ID, which must then be added to the program.
If your computer is slow and/or older, consider increasing the “mountDelay” time under “settings > advanced”.
Steps you may try in addition:
If the problem persists, enable debugging and inspect the program logfile.
This occurs when saving column-sizes on an empty table; it should normally not occur.
To fix: right-click the annotation viewer header row (with “Author”, “Title”, etc.) and select “Reset to Default”.
In case that fails:
This program’s read-only functions should(!) not be able to cause damage. We do not continuously access DBs, preferring to import data instead (at the cost of memory), minimizing the window of risk.
Program functions that modify the device’s DBs are inherently dangerous: these are the “merge/fix annotations” and “restore reading progress”:
First, always make a backup before using these tools (you are prompted to do so).
Second, take care not to disconnect the device when running these tools (take special care with worn out USB ports or cables: even a nudge can cause a disconnection).
These functions are not excempt from programming mistakes and/or compatibility problems, such as database changes after firmware updates. Checks for the latter are still in development.
Lastly, note the SQLite database (DB) commonly used by (embedded appliances such as) e-readers is robust DB format, widely used and well tested.
Over time, in discussions some topics come up repeatedly.
We provide no support for, and assume no responsibility for, trying out the discussed recovery aspects.
The various PB configuration settings files (.cfg, .dat, etc) cannot be modified. This is due to a hash signature, prompting the reader to revert to the backup file.
In case of problems, deletion can be considered, but this rarely solves problems. If so, also remove the .back copy, which is otherwise restored.
Fonts, dictionaries and apps may be restored by loading a backup archive with the “send files” tool.
Note the backup archives produced by this program are standard .zip archives. Any .zip extraction utility should be able to extract files. In addition, files are stored in their original (device-relative) paths. These may change however between firmware versions.
Restoring database files is risky and should be avoided. However, if devices have identical firmware and e-book file paths, a chance of success exists. Often there is little to lose: at worst the device can be reset again.
For PocketBooks, the main DBs of interest are:
Consider the sources of complications when replacing databases:
firmware updates: may change the database layout between versions. A manufacturer may(!) account for this during access or updates, but cannot always do so.
ebook file changes: these change ‘e-book file identifiers’, or ‘hashes’. If changed, a book file is treated as a ‘new’ book, thus losing it’s link to previously associated reading progress and annotation data.
See changelog.txt
Originally this was a set of tools for PB readers. The annotation HTML exporter was made interactive, and made the centerpiece of the UI.
We mainly provide a basic set of tools, focused on being generic and adaptable to new situations.
Content can be best managed by the e-reading device or specialized programs.
The current implementation integrates several components: an underlying reader management layer (using standard library functions, and Qt SQL functions), a Qt based mainwindow, with an integrated annotation viewer, and several tools. Future versions may see these components being split out.
At the moment, you are encouraged to donate if you are able to do so. This may change in future versions, if there are valid reasons (support load, etc.).
Transmitted data. During the optional update check, only the program platform is communicated.
Program configuration files Configuration files may contain a device’s serial, once a ‘devicelabel’ or ‘local DB mirror’ has been configured. In addition, the serial of the last used device is stored. Note: the serial can be ‘hashed’, but this gains little.
Program Backup files Largely self-explanatory: depending on the device, the archived files may include references to document title/author(s), genres, highlighted texts and user notes, if any.
Please see the website for more information.
Copyright (C) 2021-2022 Authors (See “help > about” or authors.txt)
This software is provided ‘as-is’, without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.