# `$ epy`
[](https://pepy.tech/project/epy-reader)
<a href='https://ko-fi.com/P5P4IDCX2' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi2.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
CLI Ebook Reader.
This is just a fork of [epr](https://github.com/wustho/epr) with these extra features:
- Supported formats:
- Epub (.epub, .epub3)
- FictionBook (.fb2)
- Mobi (.mobi)
- AZW3 (.azw, .azw3)
- [URL](#url-support)
- 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](#text-to-speech))
- [Double Spread](#double-spread)
- Seamless (disabled by default, read [below](#reading-tips-using-epy))
## Installation
- Via PyPI (Linux and Mac OS)
```shell
pip3 install epy-reader
```
- Via Pip+Git
```shell
pip3 install git+https://github.com/wustho/epy
```
- Via AUR
```shell
yay -S epy-ereader-git
```
- Windows Binary
Standalone binary for Windows is available at [release page](https://github.com/wustho/epy/releases).
## Usage
- `epy /path/to/your/book/book.epub` (Remember to make sure your book's title doesn't contain any spaces)
- **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
## 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 Epy
When reading using `epy` 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/epy/configuration.json` or `~/.epy/configuration.json`
- Windows: `%USERPROFILE%\.epy\configuration.json`
## URL Support
You can read online books like: short stories, fan fiction, etc. using `epy` with an url as cli argument.
Pretty useful when you want to read with less distraction.
`epy` will also remember your reading progress online.
eg. You can read [Moby Dick from gutenberg](https://www.gutenberg.org/files/2701/2701-h/2701-h.htm)
directly with:
```shell
$ epy https://www.gutenberg.org/files/2701/2701-h/2701-h.htm
```
But note that `epy` 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 `epy`.
## Using Mouse
Although mouse support is useful when running `epy` on Termux Android, it’s disabled by default
since most people find it intrusive when using `epy` 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](https://pypi.org/project/gTTS) and [MPV](https://www.mpv.io))
## 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
- `v2021.10.23`: Major refactoring which harness a lot of new stuff in `python>=3.7`
and `epy` 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 epy (default key: `R`).
- `v2022.2.5`: Fix process.join() issue for unstarted process.
- `v2022.10.2`: Major breakdown `epy.py` module into package structure for easier development.
Raw data
{
"_id": null,
"home_page": "https://github.com/wustho/epy",
"name": "epy-reader",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "ebook,epub,epub3,fb2,mobi,azw3,TUI,ebook reader",
"author": "Benawi Adha",
"author_email": "benawiadha@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/dd/7fd8a9fd26714d53471b67234e74e37ffea13eeea791a1e9d655acbf17f9/epy_reader-2023.6.11.tar.gz",
"platform": null,
"description": "# `$ epy`\n\n[](https://pepy.tech/project/epy-reader)\n\n<a href='https://ko-fi.com/P5P4IDCX2' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi2.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>\n\n\n\nCLI Ebook Reader.\n\nThis is just a fork of [epr](https://github.com/wustho/epr) with these extra features:\n\n- Supported formats:\n - Epub (.epub, .epub3)\n - FictionBook (.fb2)\n - Mobi (.mobi)\n - AZW3 (.azw, .azw3)\n - [URL](#url-support)\n- Reading progress percentage\n- Bookmarks\n- External dictionary integration (`sdcv`, `dict` or `wkdict`)\n- Inline formats: **bold** and _italic_ (depend on terminal and font capability. Italic only supported in python>=3.7)\n- Text-to-Speech (with additional setup, read [below](#text-to-speech))\n- [Double Spread](#double-spread)\n- Seamless (disabled by default, read [below](#reading-tips-using-epy))\n\n## Installation\n\n- Via PyPI (Linux and Mac OS)\n\n ```shell\n pip3 install epy-reader\n ```\n\n- Via Pip+Git\n\n ```shell\n pip3 install git+https://github.com/wustho/epy\n ```\n\n- Via AUR\n\n ```shell\n yay -S epy-ereader-git\n ```\n\n- Windows Binary\n\n Standalone binary for Windows is available at [release page](https://github.com/wustho/epy/releases).\n\n## Usage\n- `epy /path/to/your/book/book.epub` (Remember to make sure your book's title doesn't contain any spaces)\n- **c** Switching the color profile\n- **Shift + h** Previous chapter\n- **Shift + l** Next chapter\n- **Shift + g** Skip to the end of the chapter\n- **g** Skip to the beginning of the chapter\n- **Shift + m** Show metadata of the book\n- **t** Table of contents\n- **/** Search\n- **b** Add bookmark\n- **Shift + b** Show bookmarks\n- **q** Quit\n- **-** Shrink the text\n- **+** Enlarge the text\n- **o** Open an image\n- **s** Show or hide progress\n\n## Color profiles\nIn the config file you will see the following section.\n ```\n \"DarkColorFG\": 47,\n \"DarkColorBG\": 235,\n \"LightColorFG\": 238,\n \"LightColorBG\": 253,\n ```\n\nChange the values by using this image. (Make sure to ignore zeros at the beginning, it won't launch otherwise.)\n\n\n## Reading Tips Using Epy\n\nWhen reading using `epy` you might occasionally find triple asteriks `***`.\nThat means you reach the end of some section in your ebook\nand the next line (right after those three asteriks, which is in new section)\nwill start at the top of the page.\nThis might be disorienting, so the best way to get seamless reading experience\nis by using next-page control (`space`, `l` or `Right`)\ninstead of next-line control (`j` or `Down`).\n\nIf you really want to get seamless reading experience, you can set `SeamlessBetweenChapters`\nto `true` in configuration file. But it has its drawback with more memory usage, that's why\nit's disabled by default.\n\n## Configuration File\n\nConfig file is available in json format which is located at:\n\n- Linux and Mac OS: `~/.config/epy/configuration.json` or `~/.epy/configuration.json`\n- Windows: `%USERPROFILE%\\.epy\\configuration.json`\n\n## URL Support\n\nYou can read online books like: short stories, fan fiction, etc. using `epy` with an url as cli argument.\nPretty useful when you want to read with less distraction.\n`epy` will also remember your reading progress online.\n\neg. You can read [Moby Dick from gutenberg](https://www.gutenberg.org/files/2701/2701-h/2701-h.htm)\ndirectly with:\n\n```shell\n$ epy https://www.gutenberg.org/files/2701/2701-h/2701-h.htm\n```\n\nBut note that `epy` will never be a web browser, it's simply a TUI program to read\nyour favorite fiction stories in the comfort of a terminal.\nSo please do not expect for web browser features to be implemented in `epy`.\n\n## Using Mouse\n\nAlthough mouse support is useful when running `epy` on Termux Android, it\u2019s disabled by default\nsince most people find it intrusive when using `epy` in desktop.\nBut you can enable it by setting `MouseSupport` to `true` in config file.\n\n| Key | Action |\n| --- | --- |\n| `Left Click` (right side of screen) | next page |\n| `Left Click` (left side of screen) | prev page |\n| `Right Click` | ToC |\n| `Scroll Up` | scroll up |\n| `Scroll Down` | scroll down |\n| `Ctrl` + `Scroll Up` | increase text width |\n| `Ctrl` + `Scroll Down` | decrease text width |\n\n## Text-to-Speech\n\nTo get Text-to-Speech (TTS) support, external TTS engine is necessary.\n\nList of supported engines:\n\n- `mimic`\n- `pico2wave`\n- `gtts-mpv` (requires both [gTTS](https://pypi.org/project/gTTS) and [MPV](https://www.mpv.io))\n\n## Dictionary\n\nTo 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.\n\nAfter 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.\n\n## Double Spread\n\nDouble spread is intended to mimic the behaviour of real book,\nso line scrolling navigation will act as scrolling page and textwidth is not adjustable.\n\n## Changelog\n\n- `v2021.10.23`: Major refactoring which harness a lot of new stuff in `python>=3.7`\n and `epy` won't be backward compatible with older python version and older configuration.\n\n- `v2022.1.8`: Change in configuration and reading states schema that is not backward compatible.\n So if error is encountered, deleting the configuration and states file might fix the issue.\n\n- `v2022.1.15`: Early implementation of URL support, table of contents isn't available for now.\n\n- `v2022.1.23`: Library implementation: ability to switch ebook from reading history\n inside epy (default key: `R`).\n\n- `v2022.2.5`: Fix process.join() issue for unstarted process.\n\n- `v2022.10.2`: Major breakdown `epy.py` module into package structure for easier development.\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "TUI Ebook Reader",
"version": "2023.6.11",
"project_urls": {
"Homepage": "https://github.com/wustho/epy",
"Repository": "https://github.com/wustho/epy"
},
"split_keywords": [
"ebook",
"epub",
"epub3",
"fb2",
"mobi",
"azw3",
"tui",
"ebook reader"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62c77b6a90308529a0f05ecbc069f2b550ca318af5e0af32cefce1130ecb716e",
"md5": "bbd0b373f21cbd0c70baa48e1fea598e",
"sha256": "72ce1c01152fd6d63343eec7934efba6a79abc73e9b75c4af3cdccc60a80064e"
},
"downloads": -1,
"filename": "epy_reader-2023.6.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bbd0b373f21cbd0c70baa48e1fea598e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 142639,
"upload_time": "2023-06-11T05:21:41",
"upload_time_iso_8601": "2023-06-11T05:21:41.310678Z",
"url": "https://files.pythonhosted.org/packages/62/c7/7b6a90308529a0f05ecbc069f2b550ca318af5e0af32cefce1130ecb716e/epy_reader-2023.6.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "94dd7fd8a9fd26714d53471b67234e74e37ffea13eeea791a1e9d655acbf17f9",
"md5": "c50dfc81a2f8ee98a56d1ea85f831591",
"sha256": "81e979d377bc0d78eb3092bd969019e86c50b2b6a1297f928e2c91c0a6e22546"
},
"downloads": -1,
"filename": "epy_reader-2023.6.11.tar.gz",
"has_sig": false,
"md5_digest": "c50dfc81a2f8ee98a56d1ea85f831591",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 126858,
"upload_time": "2023-06-11T05:21:43",
"upload_time_iso_8601": "2023-06-11T05:21:43.868350Z",
"url": "https://files.pythonhosted.org/packages/94/dd/7fd8a9fd26714d53471b67234e74e37ffea13eeea791a1e9d655acbf17f9/epy_reader-2023.6.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-11 05:21:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wustho",
"github_project": "epy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "epy-reader"
}
JSON
