$ epw

Note: this fork is rebranded as epw. The W stands for wombat, and the rename is intended to avoid confusion with epy itself.

CLI Ebook Reader.

This is just a fork of epr with these extra features:

• Supported formats:
  • Epub (.epub, .epub3)
  • FictionBook (.fb2)
  • Mobi (.mobi)
  • AZW3 (.azw, .azw3)
  • URL
• Reading progress percentage
• Bookmarks
• External dictionary integration (sdcv, dict or wkdict)
• Inline formats: bold and italic (depend on terminal and font capability. Italic only supported in python>=3.7)
• Text-to-Speech (with additional setup, read below)
• Double Spread
• Seamless (disabled by default, read below)

Installation

From the project root, pipx install -e . works for an isolated editable install.

See INSTALL.md for the full installation options, including building packages for pip and Windows executables.

Usage

• epw /path/to/your/book/book.epub
• epw --library
• epw --history
• epw 3
• epw count monte
• c Switching the color profile
• Shift + h Previous chapter
• Shift + l Next chapter
• Shift + g Skip to the end of the chapter
• g Skip to the beginning of the chapter
• Shift + m Show metadata of the book
• t Table of contents
• / Search
• b Add bookmark
• Shift + b Show bookmarks
• q Quit
• - Shrink the text
• + Enlarge the text
• o Open an image
• s Show or hide progress

epw --library presents the reading history and prompts you to choose an entry to open or quit. epw --history prints the same history list without opening anything.

Color profiles

In the config file you will see the following section.

 "DarkColorFG": 47,
 "DarkColorBG": 235,
 "LightColorFG": 238,
 "LightColorBG": 253,

Change the values by using this image. (Make sure to ignore zeros at the beginning, it won't launch otherwise.)

Reading Tips Using Epw

When reading using epw you might occasionally find triple asteriks ***. That means you reach the end of some section in your ebook and the next line (right after those three asteriks, which is in new section) will start at the top of the page. This might be disorienting, so the best way to get seamless reading experience is by using next-page control (space, l or Right) instead of next-line control (j or Down).

If you really want to get seamless reading experience, you can set SeamlessBetweenChapters to true in configuration file. But it has its drawback with more memory usage, that's why it's disabled by default.

Configuration File

Config file is available in json format which is located at:

• Linux and Mac OS: ~/.config/epw/configuration.json or ~/.epw/configuration.json
• Windows: %USERPROFILE%\.epw\configuration.json

URL Support

You can read online books like: short stories, fan fiction, etc. using epw with an url as cli argument. Pretty useful when you want to read with less distraction. epw will also remember your reading progress online.

eg. You can read Moby Dick from gutenberg directly with:

$ epw https://www.gutenberg.org/files/2701/2701-h/2701-h.htm

But note that epw will never be a web browser, it's simply a TUI program to read your favorite fiction stories in the comfort of a terminal. So please do not expect for web browser features to be implemented in epw.

Using Mouse

Although mouse support is useful when running epw on Termux Android, it’s disabled by default since most people find it intrusive when using epw in desktop. But you can enable it by setting MouseSupport to true in config file.

Key	Action
Left Click (right side of screen)	next page
Left Click (left side of screen)	prev page
Right Click	ToC
Scroll Up	scroll up
Scroll Down	scroll down
Ctrl + Scroll Up	increase text width
Ctrl + Scroll Down	decrease text width

Text-to-Speech

To get Text-to-Speech (TTS) support, external TTS engine is necessary.

List of supported engines:

• mimic
• pico2wave
• gtts-mpv (requires both gTTS and MPV)

Dictionary

To use "Define Word" you will have to install an external dictionary cli program (sdcv, dict or wkdict). After you've done that, it is recommended to manually modify the configuration.json file, and set your desired dictionary there, so everything works properly.

After that you will be able to find definition of word by pressing d, and aprompt will appear to let you type in word to define.

Double Spread

Double spread is intended to mimic the behaviour of real book, so line scrolling navigation will act as scrolling page and textwidth is not adjustable.

Changelog

• v0.9.1: Added a --library CLI mode that shows reading history and prompts for a selection, updated the CLI help text and README usage examples, and added tests for the new history-selection prompt.

• v0.9.0: Rebranded the program from epy to epw, renamed the installable package to epw-reader, changed configuration paths to ~/.config/epw and ~/.epw, removed the imghdr dependency in the Kindle/MOBI cover handling path for newer Python compatibility, documented installation including pipx, and switched project versioning to semantic versioning.

• v2021.10.23: Major refactoring which harness a lot of new stuff in python>=3.7 and epw won't be backward compatible with older python version and older configuration.

• v2022.1.8: Change in configuration and reading states schema that is not backward compatible. So if error is encountered, deleting the configuration and states file might fix the issue.

• v2022.1.15: Early implementation of URL support, table of contents isn't available for now.

• v2022.1.23: Library implementation: ability to switch ebook from reading history inside epw (default key: R).

• v2022.2.5: Fix process.join() issue for unstarted process.

• v2022.10.2: Major breakdown of the main module into package structure for easier development.

AI Usage

The code in this repository has been to some degree written or altered by an AI tool with human supervision. Usually that either means that I have written (or have) the functionality in another language, or that my understanding of that programming language (or technique) is limited. At most, the instructions to the AI agents were also very detailed, step-by-step pseudocode with very specific limitations. When putting together this code, I audited, wrote, edited, or rewrote large chunks of it. This could be characterized as "assisted". Again, while the code in this repository works for me and I am using it, it should be considered a proof-of-concept for others to refine, fix, and build upon.

You are encouraged to fork and refine or rebuild this program or create something better that has the same functionality.