{"id":24883048,"url":"https://github.com/0x6f677548/intellireading-cli","last_synced_at":"2025-10-16T02:30:33.952Z","repository":{"id":273181182,"uuid":"851691804","full_name":"0x6f677548/intellireading-cli","owner":"0x6f677548","description":"A client tool and python library to generate metaguided versions of your ebooks, improving your reading focus and speed","archived":false,"fork":false,"pushed_at":"2025-01-22T16:16:13.000Z","size":6016,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-27T07:08:31.906Z","etag":null,"topics":["adhd","bionic-reading","ebook","epub","kepub","kindle","kobo","speed-reading"],"latest_commit_sha":null,"homepage":"https://www.intellireading.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0x6f677548.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":1869051208}},"created_at":"2024-09-03T14:52:01.000Z","updated_at":"2025-01-25T07:39:41.000Z","dependencies_parsed_at":"2025-01-19T09:21:48.775Z","dependency_job_id":"89e16e92-28a7-4952-b215-4460c4d932f6","html_url":"https://github.com/0x6f677548/intellireading-cli","commit_stats":null,"previous_names":["0x6f677548/intellireading-cli"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x6f677548%2Fintellireading-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x6f677548%2Fintellireading-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x6f677548%2Fintellireading-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x6f677548%2Fintellireading-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0x6f677548","download_url":"https://codeload.github.com/0x6f677548/intellireading-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236664639,"owners_count":19185537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adhd","bionic-reading","ebook","epub","kepub","kindle","kobo","speed-reading"],"created_at":"2025-02-01T13:17:48.845Z","updated_at":"2025-10-16T02:30:33.946Z","avatar_url":"https://github.com/0x6f677548.png","language":"Python","funding_links":["https://github.com/sponsors/1869051208"],"categories":[],"sub_categories":[],"readme":"![Intellireading.com](https://go.hugobatista.com/ghraw/intellireading-www/main/src/img/intellireading.png)\n# Standalone tool and library\n\n[![PyPI - Version](https://img.shields.io/pypi/v/intellireading-cli.svg)](https://pypi.org/project/intellireading-cli)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/intellireading-cli.svg)](https://pypi.org/project/intellireading-cli)\n[![Deploy to ghcr.io](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/build-and-publish-to-ghcr.yml/badge.svg)](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/build-and-publish-to-ghcr.yml)\n[![Lint](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/lint.yml/badge.svg)](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/lint.yml)\n[![Test](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/test.yml/badge.svg)](https://go.hugobatista.com/gh/intellireading-cli/actions/workflows/test.yml)\n[![GitMCP](https://img.shields.io/endpoint?url=https://gitmcp.io/badge/0x6f677548/intellireading-cli)](https://gitmcp.io/0x6f677548/intellireading-cli)\n\nIntellireading is a CLI tool with commands to accelerate your reading experience. It can also be used as a Python library.\nCurrently, it supports metaguiding an EPUB, KEPUB, XHTML, or HTML file (more features coming):\n```console\n\u003e intellireading metaguide-epub --input_file mybook.epub --output_file mybook_metaguided.epub\n```\nExample of a text converted to a metaguided text:\n![Intellireading.com](https://go.hugobatista.com/ghraw/intellireading-www/main/src/img/sample.png) \n\n\nThis repo is part of the [Intellireading](https://intellireading.com/) project, which aims to help people with dyslexia, ADHD, or anyone who wants to improve their reading focus and speed. \n\n## [Other Intellireading Code Repositories](https://go.hugobatista.com/ghstars/lists/intellireading)\n- [Intellireading website](https://go.hugobatista.com/gh/intellireading-www), which allows anyone to convert an Epub to the metaguided version.\n- [API Server](https://go.hugobatista.com/gh/intellireading-api_server), that support the Intellireading website.\n- [CLI Tool](https://go.hugobatista.com/gh/intellireading-cli). A standalone tool and library that can be used to metaguide epub files.\n- [Calibre Plugins](https://go.hugobatista.com/gh/intellireading-calibre-plugins). A set of plugins that can be used to metaguide epub files using Calibre.\n\n\n## What is EPUB Metaguiding?\n**Metagu**iding **i**s **a** **techn**ique **th**at **ca**n **b**e **us**ed **t**o **impr**ove **yo**ur **read**ing **foc**us **an**d **spe**ed **(some**times **cal**led **Bio**nic **Readi**ng). **I**t **i**s **bas**ed **o**n **th**e **id**ea **th**at **yo**u **ca**n **us**e **a** **vis**ual **gui**de **t**o **he**lp **yo**ur **ey**es **foc**us **o**n **th**e **te**xt **yo**u **ar**e **read**ing. **I**n **th**is **cas**e, **th**e **vis**ual **gui**de **i**s **do**ne **b**y **bold**ing **a** **pa**rt **o**f **th**e **tex**t, **crea**ting **vis**ual **anch**ors **th**at **yo**ur **ey**es **ca**n **us**e **t**o **foc**us **o**n **th**e **tex**t. **Th**is **i**s **simi**lar **t**o **th**e **wa**y **a** **fin**ger **ca**n **b**e **us**ed **t**o **gui**de **yo**ur **ey**es **alo**ng **a** **li**ne **o**f **tex**t, **whi**ch **ha**s **be**en **sho**wn **t**o **impr**ove **read**ing **spe**ed **an**d **foc**us. ([**stu**dy: **\"Do**es **finger-t**racking **poi**nt **t**o **chi**ld **read**ing **strate**gies\"](https://ceur-ws.org/Vol-2769/paper_60.pdf))\n\n**Howe**ver, **unl**ike **a** **fing**er, **th**e **vis**ual **gui**de **i**s **no**t **distra**cting, **an**d **i**t **ca**n **b**e **us**ed **t**o **gui**de **yo**ur **ey**es **alo**ng **mult**iple **lin**es **o**f **te**xt **a**t **onc**e. **Th**is **all**ows **yo**u **t**o **re**ad **fast**er, **an**d **wi**th **le**ss **effo**rt.\n\n**Metagu**iding **i**s **partic**ulary **use**ful **fo**r **peo**ple **wi**th **dysl**exia **o**r **ADH**D, **bu**t **i**t **ca**n **b**e **us**ed **b**y **any**one **wh**o **wan**ts **t**o **impr**ove **the**ir **read**ing **foc**us **an**d **spe**ed. **Fo**r **mo**re **inform**ation, **vis**it **th**e [**Intelli**reading **webs**ite.](https://intellireading.com/)\n\n## Features\n\nIntellireading commands can be used to:\n- **Metaguide an EPUB file**: Metaguide an EPUB file, transforming it into a metaguided EPUB file, by transforming all XHTML files in the EPUB file into metaguided XHTML files.\n- **Metaguide an XHTML file**: Metaguide an XHTML file, transforming it into a metaguided XHTML file.\n- **Metaguide a directory**: Metaguide all files in a directory, transforming all EPUB, XHTML, and HTML files into metaguided files.\n\n## Installation\n\nIntellireading is a command line tool that can be used in Windows, Linux, and MacOS. It is written in Python and can be used as a module or as a standalone tool, as long as you have Python \u003e3.7 installed (or Docker).\n\n### pip\nTo install it, you can use pip:\n```console\n\u003e pip install intellireading-cli\n\u003e intellireading --help\n```\n\n### From source code\nYou can also install it from the source code:\n```console\n\u003e git clone https://go.hugobatista.com/gh/intellireading-cli.git\n\u003e cd intellireading-cli\n\u003e pip install .\n\u003e intellireading --help\n```\n\n### Docker\nAlternatively, you can use the Docker image:\n\n#### Help command\n```console\n\u003e docker pull ghcr.io/0x6f677548/intellireading-cli:latest\n\u003e docker run -it --rm ghcr.io/0x6f677548/intellireading-cli --help\n```\n\n#### Metaguide an EPUB file\n##### Linux/MacOS\n```console\n\u003e docker run -it --rm -v $(pwd)/tests:/tests ghcr.io/0x6f677548/intellireading-cli metaguide-epub --input_file '/tests/test_files/input.epub' --output_file '/tests/test_files/output.epub'\n```\n##### Windows\n```powershell\n\u003e docker run -it --rm -v ${pwd}/tests:/tests ghcr.io/0x6f677548/intellireading-cli metaguide-epub --input_file '/tests/test_files/input.epub' --output_file '/tests/test_files/output.epub'\n```\n\n## CLI Usage\n\nAll available commands and options can be seen by using the `--help` option.\n```console\n\u003e intellireading --help\n```\n\nTo get help on a specific command, use the `--help` option with the command name. For example, to get help on the `metaguide-epub` command, use the following command:\n```console\n\u003e intellireading metaguide-epub --help\n```\n\nIntellireading is based on [Click](https://github.com/pallets/click/), taking advantage of its features, such as chaining commands and options. \n\n### CLI Examples\n\n#### Metaguide an EPUB file\nTo metaguide an EPUB file, use the `metaguide-epub` command. The command requires the path to the EPUB file and the output file. The output file will be a metaguided epub file. \n\n```console\n\u003e intellireading metaguide-epub --input_file mybook.epub --output_file mybook_metaguided.epub\n```\n\n#### Metaguide a XHTML file\nTo metaguide an XHTML file, use the `metaguide-xhtml` command. The command requires the path to the XHTML file and the output file. The output file will be a metaguided xhtml file. \n\n```console\n\u003e intellireading metaguide-xhtml --input_file mybook.xhtml --output_file mybook_metaguided.xhtml\n```\n\n#### Metaguide all files in a directory\nTo metaguide all files in a directory, use the `metaguide-dir` command. The command requires the path to the directory and the output directory. The output directory will contain all metaguided files, including epub, xhtml and html files. \n\n```console\n\u003e intellireading metaguide-dir --input_dir mydir --output_dir mydir_metaguided\n```\n\n## Experimental Features\nSome features are still experimental and may not work as expected. Use them with caution.\n\n### Remove metaguiding\nThe remove metaguiding feature allows you to remove metaguiding from previous metaguided files. This implementation is still experimental and may not work as expected, since it is not possible to recover the original text. The current implementation tries to remove the metaguiding by removing the bold tags from the text, but that may imply in some original text format loss.\n\n#### Remove metaguiding from an EPUB file\nTo remove metaguiding from an EPUB file, use the --remove_metaguiding flag. The command requires the path to the EPUB file and the output file. The output file will be an epub file without metaguiding. \n\n```console\n\u003e intellireading metaguide-epub --remove_metaguiding --input_file mybook_metaguided.epub --output_file mybook.epub\n```\n\n#### Remove metaguiding from a XHTML file\nTo remove metaguiding from a XHTML file, use the --remove_metaguiding flag. The command requires the path to the XHTML file and the output file. The output file will be an xhtml file without metaguiding. \n\n```console\n\u003e intellireading metaguide-xhtml --remove_metaguiding --input_file mybook_metaguided.xhtml --output_file mybook.xhtml\n```\n\n#### Remove metaguiding from all files in a directory\nTo remove metaguiding from all files in a directory, use the --remove_metaguiding flag. The command requires the path to the directory and the output directory. The output directory will contain all files without metaguiding, including epub, xhtml and html files. \n\n```console\n\u003e intellireading metaguide-dir --remove_metaguiding --input_dir mydir_metaguided --output_dir mydir\n```\n\n## Python Library API\n\nThe intellireading-cli package can be used as a Python library for programmatic access to metaguiding functionality. This is useful for integrating metaguiding into web applications, batch processing scripts, or other Python projects.\n\n### Quick Start\n\n```python\nfrom intellireading.client import (\n    metaguide_epub_file,\n    metaguide_xhtml_file,\n    metaguide_epub_stream,\n    metaguide_xhtml_stream,\n    metaguide_dir,\n    is_file_metaguided\n)\n\n# Metaguide an EPUB file\nmetaguide_epub_file(\"input.epub\", \"output.epub\")\n\n# Metaguide an XHTML file\nmetaguide_xhtml_file(\"input.html\", \"output.html\")\n```\n\n### Core Functions\n\n#### EPUB Functions\n\n**`metaguide_epub_file(input_file: str, output_file: str, *, remove_metaguiding: bool = False)`**\n\nMetaguides an EPUB file by applying visual anchoring to text content within all XHTML files in the EPUB.\n\n```python\nfrom intellireading.client import metaguide_epub_file\n\n# Basic metaguiding\nmetaguide_epub_file(\"mybook.epub\", \"mybook_metaguided.epub\")\n\n# Remove metaguiding (experimental)\nmetaguide_epub_file(\n    \"mybook_metaguided.epub\", \n    \"mybook_original.epub\", \n    remove_metaguiding=True\n)\n```\n\n**`metaguide_epub_stream(input_stream: BytesIO, *, remove_metaguiding: bool = False) -\u003e BytesIO`**\n\nMetaguides an EPUB from a byte stream, useful for in-memory processing or web applications.\n\n```python\nfrom io import BytesIO\nfrom intellireading.client import metaguide_epub_stream\n\n# Read EPUB into memory\nwith open(\"input.epub\", \"rb\") as f:\n    input_stream = BytesIO(f.read())\n\n# Metaguide the stream\noutput_stream = metaguide_epub_stream(input_stream)\n\n# Write to file\nwith open(\"output.epub\", \"wb\") as f:\n    f.write(output_stream.read())\n```\n\n#### XHTML Functions\n\n**`metaguide_xhtml_file(input_file: str, output_file: str, *, remove_metaguiding: bool = False)`**\n\nMetaguides an XHTML/HTML file by applying visual anchoring to text content. Supports `.xhtml`, `.html`, and `.htm` files.\n\n```python\nfrom intellireading.client import metaguide_xhtml_file\n\n# Metaguide an HTML file\nmetaguide_xhtml_file(\"article.html\", \"article_metaguided.html\")\n\n# Remove metaguiding\nmetaguide_xhtml_file(\n    \"article_metaguided.html\", \n    \"article_restored.html\", \n    remove_metaguiding=True\n)\n```\n\n**`metaguide_xhtml_stream(input_file_stream: BytesIO, *, remove_metaguiding: bool = False) -\u003e BytesIO`**\n\nMetaguides an XHTML/HTML file from a byte stream.\n\n```python\nfrom io import BytesIO\nfrom intellireading.client import metaguide_xhtml_stream\n\n# Process HTML content from string\nhtml_content = \"\"\"\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n    \u003cp\u003eThis is a sample paragraph that will be metaguided.\u003c/p\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n\"\"\"\n\ninput_stream = BytesIO(html_content.encode('utf-8'))\noutput_stream = metaguide_xhtml_stream(input_stream)\nmetaguided_content = output_stream.read().decode('utf-8')\n```\n\n#### Directory Functions\n\n**`metaguide_dir(input_dir: str, output_dir: str, *, remove_metaguiding: bool = False)`**\n\nMetaguides all EPUB and XHTML/HTML files found in a directory recursively.\n\n```python\nfrom intellireading.client import metaguide_dir\n\n# Metaguide all books in the directory\nmetaguide_dir(\"books\", \"books_metaguided\")\n\n# Remove metaguiding from all files\nmetaguide_dir(\"books_metaguided\", \"books_restored\", remove_metaguiding=True)\n```\n\n#### Utility Functions\n\n**`is_file_metaguided(filepath: str) -\u003e bool`**\n\nChecks if an EPUB file has already been metaguided.\n\n```python\nfrom intellireading.client import is_file_metaguided, metaguide_epub_file\n\n# Check if file is already metaguided\nif not is_file_metaguided(\"mybook.epub\"):\n    metaguide_epub_file(\"mybook.epub\", \"mybook_metaguided.epub\")\n    print(\"File metaguided successfully\")\nelse:\n    print(\"File is already metaguided\")\n```\n\n### Integration Examples\n\n#### Web Application (Flask)\n\n```python\nfrom flask import Flask, request, send_file\nfrom io import BytesIO\nfrom intellireading.client import metaguide_epub_stream\n\napp = Flask(__name__)\n\n@app.route('/metaguide', methods=['POST'])\ndef metaguide_upload():\n    file = request.files['epub']\n    if file and file.filename.endswith('.epub'):\n        input_stream = BytesIO(file.read())\n        output_stream = metaguide_epub_stream(input_stream)\n        \n        return send_file(\n            output_stream,\n            as_attachment=True,\n            download_name=f\"metaguided_{file.filename}\",\n            mimetype='application/epub+zip'\n        )\n    return \"Invalid file\", 400\n```\n\n#### Batch Processing\n\n```python\nimport os\nfrom intellireading.client import metaguide_dir, is_file_metaguided\n\ndef batch_process_library(library_path):\n    \"\"\"Process an entire library of EPUB files\"\"\"\n    processed_path = os.path.join(library_path, \"metaguided\")\n    \n    # Process all files\n    metaguide_dir(library_path, processed_path)\n    \n    # Verify results\n    for root, dirs, files in os.walk(processed_path):\n        for file in files:\n            if file.endswith('.epub'):\n                filepath = os.path.join(root, file)\n                if is_file_metaguided(filepath):\n                    print(f\"✓ Successfully metaguided: {file}\")\n\nbatch_process_library(\"/path/to/my/books\")\n```\n\n### Error Handling\n\n```python\nfrom intellireading.client import metaguide_epub_file\n\ntry:\n    metaguide_epub_file(\"mybook.epub\", \"output.epub\")\nexcept ValueError as e:\n    print(f\"Invalid file: {e}\")\nexcept FileNotFoundError as e:\n    print(f\"File not found: {e}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x6f677548%2Fintellireading-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0x6f677548%2Fintellireading-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x6f677548%2Fintellireading-cli/lists"}