Standalone tool and library

Intellireading is a CLI tool with commands to accelerate your reading experience. It can also be used as a Python library. Currently, it supports metaguiding an EPUB, KEPUB, XHTML, or HTML file (more features coming):

> intellireading metaguide-epub --input_file mybook.epub --output_file mybook_metaguided.epub

Example of a text converted to a metaguided text:

This repo is part of the Intellireading project, which aims to help people with dyslexia, ADHD, or anyone who wants to improve their reading focus and speed.

Other Intellireading Code Repositories

Intellireading website, which allows anyone to convert an Epub to the metaguided version.
API Server, that support the Intellireading website.
CLI Tool. A standalone tool and library that can be used to metaguide epub files.
Calibre Plugins. A set of plugins that can be used to metaguide epub files using Calibre.

What is EPUB Metaguiding?

Metaguiding is a technique that can be used to improve your reading focus and speed (sometimes called Bionic Reading). It is based on the idea that you can use a visual guide to help your eyes focus on the text you are reading. In this case, the visual guide is done by bolding a part of the text, creating visual anchors that your eyes can use to focus on the text. This is similar to the way a finger can be used to guide your eyes along a line of text, which has been shown to improve reading speed and focus. (study: "Does finger-tracking point to child reading strategies")

However, unlike a finger, the visual guide is not distracting, and it can be used to guide your eyes along multiple lines of text at once. This allows you to read faster, and with less effort.

Metaguiding is particulary useful for people with dyslexia or ADHD, but it can be used by anyone who wants to improve their reading focus and speed. For more information, visit the Intellireading website.

Features

Intellireading commands can be used to:

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.
Metaguide an XHTML file: Metaguide an XHTML file, transforming it into a metaguided XHTML file.
Metaguide a directory: Metaguide all files in a directory, transforming all EPUB, XHTML, and HTML files into metaguided files.

Installation

Intellireading 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 >3.7 installed (or Docker).

pip

To install it, you can use pip:

> pip install intellireading-cli
> intellireading --help

From source code

You can also install it from the source code:

> git clone https://go.hugobatista.com/gh/intellireading-cli.git
> cd intellireading-cli
> pip install .
> intellireading --help

Docker

Alternatively, you can use the Docker image:

Help command

> docker pull ghcr.io/0x6f677548/intellireading-cli:latest
> docker run -it --rm ghcr.io/0x6f677548/intellireading-cli --help

Metaguide an EPUB file

Linux/MacOS

> 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'

Windows

> 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'

CLI Usage

All available commands and options can be seen by using the --help option.

> intellireading --help

To 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:

> intellireading metaguide-epub --help

Intellireading is based on Click, taking advantage of its features, such as chaining commands and options.

CLI Examples

Metaguide an EPUB file

To 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.

> intellireading metaguide-epub --input_file mybook.epub --output_file mybook_metaguided.epub

Metaguide a XHTML file

To 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.

> intellireading metaguide-xhtml --input_file mybook.xhtml --output_file mybook_metaguided.xhtml

Metaguide all files in a directory

To 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.

> intellireading metaguide-dir --input_dir mydir --output_dir mydir_metaguided

Experimental Features

Some features are still experimental and may not work as expected. Use them with caution.

Remove metaguiding

The 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.

Remove metaguiding from an EPUB file

To 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.

> intellireading metaguide-epub --remove_metaguiding --input_file mybook_metaguided.epub --output_file mybook.epub

Remove metaguiding from a XHTML file

To 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.

> intellireading metaguide-xhtml --remove_metaguiding --input_file mybook_metaguided.xhtml --output_file mybook.xhtml

Remove metaguiding from all files in a directory

To 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.

> intellireading metaguide-dir --remove_metaguiding --input_dir mydir_metaguided --output_dir mydir

Python Library API

The 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.

Quick Start

from intellireading.client import (
    metaguide_epub_file,
    metaguide_xhtml_file,
    metaguide_epub_stream,
    metaguide_xhtml_stream,
    metaguide_dir,
    is_file_metaguided
)

# Metaguide an EPUB file
metaguide_epub_file("input.epub", "output.epub")

# Metaguide an XHTML file
metaguide_xhtml_file("input.html", "output.html")

Core Functions

EPUB Functions

metaguide_epub_file(input_file: str, output_file: str, *, remove_metaguiding: bool = False)

Metaguides an EPUB file by applying visual anchoring to text content within all XHTML files in the EPUB.

from intellireading.client import metaguide_epub_file

# Basic metaguiding
metaguide_epub_file("mybook.epub", "mybook_metaguided.epub")

# Remove metaguiding (experimental)
metaguide_epub_file(
    "mybook_metaguided.epub", 
    "mybook_original.epub", 
    remove_metaguiding=True
)

metaguide_epub_stream(input_stream: BytesIO, *, remove_metaguiding: bool = False) -> BytesIO

Metaguides an EPUB from a byte stream, useful for in-memory processing or web applications.

from io import BytesIO
from intellireading.client import metaguide_epub_stream

# Read EPUB into memory
with open("input.epub", "rb") as f:
    input_stream = BytesIO(f.read())

# Metaguide the stream
output_stream = metaguide_epub_stream(input_stream)

# Write to file
with open("output.epub", "wb") as f:
    f.write(output_stream.read())

XHTML Functions

metaguide_xhtml_file(input_file: str, output_file: str, *, remove_metaguiding: bool = False)

Metaguides an XHTML/HTML file by applying visual anchoring to text content. Supports .xhtml, .html, and .htm files.

from intellireading.client import metaguide_xhtml_file

# Metaguide an HTML file
metaguide_xhtml_file("article.html", "article_metaguided.html")

# Remove metaguiding
metaguide_xhtml_file(
    "article_metaguided.html", 
    "article_restored.html", 
    remove_metaguiding=True
)

metaguide_xhtml_stream(input_file_stream: BytesIO, *, remove_metaguiding: bool = False) -> BytesIO

Metaguides an XHTML/HTML file from a byte stream.

from io import BytesIO
from intellireading.client import metaguide_xhtml_stream

# Process HTML content from string
html_content = """
<!DOCTYPE html>
<html>
<body>
    <p>This is a sample paragraph that will be metaguided.</p>
</body>
</html>
"""

input_stream = BytesIO(html_content.encode('utf-8'))
output_stream = metaguide_xhtml_stream(input_stream)
metaguided_content = output_stream.read().decode('utf-8')

Directory Functions

metaguide_dir(input_dir: str, output_dir: str, *, remove_metaguiding: bool = False)

Metaguides all EPUB and XHTML/HTML files found in a directory recursively.

from intellireading.client import metaguide_dir

# Metaguide all books in the directory
metaguide_dir("books", "books_metaguided")

# Remove metaguiding from all files
metaguide_dir("books_metaguided", "books_restored", remove_metaguiding=True)

Utility Functions

is_file_metaguided(filepath: str) -> bool

Checks if an EPUB file has already been metaguided.

from intellireading.client import is_file_metaguided, metaguide_epub_file

# Check if file is already metaguided
if not is_file_metaguided("mybook.epub"):
    metaguide_epub_file("mybook.epub", "mybook_metaguided.epub")
    print("File metaguided successfully")
else:
    print("File is already metaguided")

Integration Examples

Web Application (Flask)

from flask import Flask, request, send_file
from io import BytesIO
from intellireading.client import metaguide_epub_stream

app = Flask(__name__)

@app.route('/metaguide', methods=['POST'])
def metaguide_upload():
    file = request.files['epub']
    if file and file.filename.endswith('.epub'):
        input_stream = BytesIO(file.read())
        output_stream = metaguide_epub_stream(input_stream)
        
        return send_file(
            output_stream,
            as_attachment=True,
            download_name=f"metaguided_{file.filename}",
            mimetype='application/epub+zip'
        )
    return "Invalid file", 400

Batch Processing

import os
from intellireading.client import metaguide_dir, is_file_metaguided

def batch_process_library(library_path):
    """Process an entire library of EPUB files"""
    processed_path = os.path.join(library_path, "metaguided")
    
    # Process all files
    metaguide_dir(library_path, processed_path)
    
    # Verify results
    for root, dirs, files in os.walk(processed_path):
        for file in files:
            if file.endswith('.epub'):
                filepath = os.path.join(root, file)
                if is_file_metaguided(filepath):
                    print(f"✓ Successfully metaguided: {file}")

batch_process_library("/path/to/my/books")

Error Handling

from intellireading.client import metaguide_epub_file

try:
    metaguide_epub_file("mybook.epub", "output.epub")
except ValueError as e:
    print(f"Invalid file: {e}")
except FileNotFoundError as e:
    print(f"File not found: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")