# User manual — The Reader's apps and the other apps of gallaz.ch/apps

Edition of 7 October 2026 · gallaz.ch/apps


<!-- Before you start -->


# About this manual

*One chapter per app; every chapter has the same sections.*

## What it covers

This manual describes the apps published at gallaz.ch/apps: the Reader's family (a whole phone in black and white, text only), the four other apps offered by its installer, the three meditation apps, and a few browser extensions and Linux tools. Several Reader's apps also exist for Windows, macOS and Linux; the computer version is described in the same chapter as the phone version.

Each chapter was written from the app itself: its screens, its settings and the exact words it displays. A label printed in **bold** is a label you will find, spelled that way, in the app. The version described is given under each chapter's title; a newer version may have moved or added something.

## How each chapter is organised

| Section | What you find there |
|---|---|
| What it is | What the app does, and what it deliberately does not do |
| First start | What the app asks the first time, and what to enter |
| The screens | Every screen, and every control on it |
| How to | Step-by-step answers to practical questions |
| Settings | Every setting, its choices and its default |
| Your data | Where your data lives, what travels over the network, export and backup |
| With the other apps | Widgets, launcher tiles and links between apps |
| On the computer | The Windows, macOS or Linux version, when there is one |
| Limits | What the app does not do |
| Messages and problems | What the app's messages mean, and what to do |

## Asking an AI assistant

The manual is also meant to be given to an AI assistant, so that a new user can simply ask a question.

1. Give the assistant this file: the PDF, or the text version published next to it (the same content, lighter to read for a machine).
2. Ask your question in your own words, naming the app: "In Reader's Calendar, how do I make an event repeat every week?"
3. If the answer does not match what you see, tell the assistant which version of the app you have (Android shows it in its own settings, under Apps, at the bottom of the app's page).

A useful instruction to add: "Answer only from the manual. Quote the labels as they are written. If the manual does not say, say so."

## Where to get help

The apps are free and open source. Each app's page on gallaz.ch/apps has a **Source** link to its repository, where problems can be reported.


# Getting the apps

*Android phones and tablets; Windows, macOS and Linux for the desktop versions.*

## The short way: the installer

One small app, Reader's Installer and Updater, installs all the others and keeps them up to date. Every app of the Reader's family is in its list, with ePub Magazine Reader, Le dictionnaire Littré, Clavier Plume and Funky's 2P Games.

1. On the phone, open gallaz.ch/apps and tap **Download the installer (APK)**, then open the downloaded file. Android asks once to let the browser install apps: allow it.
2. Open Reader's Installer. The apps are in the list: tap one, then **Install**. Android asks once to let the installer install apps.
3. That is all. Updates are looked for in the background; on Android 12 and later they install silently for the apps the installer installed itself.

The installer is for 64-bit ARM devices, which is nearly every phone and tablet since 2017. An app installed earlier from F-Droid or from an APK file asks once for confirmation, then follows the installer's updates. The installer has its own chapter in this manual.

## Three other ways

The files are identical and carry the same signature whichever way you choose, so you can change your mind later without uninstalling anything.

### F-Droid (updates arrive by themselves)

1. Install the F-Droid client (Droid-ify or Neo Store work too).
2. Add the repository: on gallaz.ch/apps tap **Add to F-Droid** on the phone, or scan the code shown there from a computer. The repository's address is `https://funkypitt.github.io/fdroid-repo/repo` and its fingerprint is `64191E58C98AD1971BCA0669B6BFAB5C7135D6411A8EAA252741C2D35F16107C`.
3. Refresh, search for the app, install. F-Droid then keeps every app up to date.

### Obtainium (updates straight from GitHub)

Obtainium installs and updates apps from their GitHub releases, with no store in between. With Obtainium on the phone, tap the **Obtainium** button of any app on gallaz.ch/apps. The link opens Obtainium directly and goes through no third-party page.

### The APK file (last resort: no updates)

Each app on gallaz.ch/apps also has an **APK** link. Installed this way, an app never updates: you would have to come back for every new version. Use it to try an app, or on a device where neither F-Droid nor Obtainium can run.

## On the computer

Reader's Calendar, Reader's Tasks, Reader's Notes and Reader's Scanner also exist for Windows, macOS and Linux, and Reader's Podcasts for Linux. The download button is on each app's card on gallaz.ch/apps; in the installer, the app's page links to its desktop version.

### Debian, Ubuntu, Pop!_OS, Mint: the apt repository

The five desktop apps are in a small apt repository, so they update with the rest of the system:

```
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://funkypitt.github.io/apt-repo/funkypitt.gpg | sudo tee /etc/apt/keyrings/funkypitt.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/funkypitt.gpg] https://funkypitt.github.io/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/funkypitt.list
sudo apt update && sudo apt install readers-calendar readers-notes readers-tasks readers-scanner readers-podcasts
```

On Arch Linux, each app's repository has a PKGBUILD. Details are at funkypitt.github.io/apt-repo.

### Windows and macOS: the first opening

Reader's Calendar, Reader's Notes and Reader's Tasks come as an .exe for Windows and a .dmg for macOS, on each app's download page: one file, nothing to install. They are small free applications without a paid certificate, so the system distrusts them once, and once only.

- **Windows:** a blue "Windows protected your PC" panel appears the first time. Choose **More info**, then **Run anyway**.
- **macOS:** open the .dmg ("apple-silicon" for an M1 Mac or later, "intel" for an older one), drag the app onto Applications, then right click on the app, choose **Open**, and **Open** again. A double click at that point only says the app cannot be opened. Afterwards it opens like any other.


# Common to the Reader's apps

*What is the same from one Reader's app to the next: the look, the languages, your own server, the credentials file.*

## The look

Every Reader's app is text only, in black and white: no icons, no colours, no cards. Most of them let you choose between **white on black** and **black on white**, either as an entry of the **⋯** menu or as a **colours** setting; each chapter says where. The text size and the font are settings of each app.

## Languages

The Reader's apps exist in English, French, German, Spanish, Portuguese and Russian. An app follows the language of the phone; on Android 13 and later, Android's own settings let you choose a language for one app. Where an app is not fully translated, its chapter says so. The meditation apps (Retreat Timer, Retreat Player, Retreat Walk) are in English only.

## No account, your own server

No app asks you to create an account with its author, and none shows advertising. Data stays on the phone unless you connect a server of your own; each chapter's "Your data" section says exactly what travels and to whom, including the few cases where a third party is involved.

Some apps can keep their data in step with your other devices through a server you already have. Two standard kinds of server are used:

| App | What it connects to | Needed? |
|---|---|---|
| Reader's Tasks (phone and computer) | a CalDAV server holding task lists | yes |
| Reader's Calendar on the computer | a CalDAV server holding calendars | yes |
| Reader's Calendar on the phone | nothing: it shows the calendars the phone already syncs | no |
| Reader's Notes (phone and computer) | a WebDAV folder | optional |
| Reader's Scanner (phone and computer) | a WebDAV folder | optional |
| Reader's Recorder | a WebDAV folder | optional |

### What to type for Infomaniak

- **Calendars and tasks (CalDAV):** server `https://sync.infomaniak.com`, a username of the form `AB12345`, and your password. If two-factor authentication is on, create an application password in the Infomaniak Manager and use that one.
- **Files (WebDAV, kDrive):** server `https://ID.connect.kdrive.infomaniak.com`, where ID is the number in your kDrive's web address, then your Infomaniak login and password (an application password if two-factor authentication is on). According to Infomaniak's help pages, WebDAV access is not included in the free kDrive that comes with a free ik.me address.

### What to type for Nextcloud

- **Calendars and tasks (CalDAV):** server `https://your-server/remote.php/dav`.
- **Files (WebDAV):** server `https://your-server/remote.php/dav/files/USERNAME`, where USERNAME is your Nextcloud login name.
- In both cases the username is your Nextcloud login name, and the password is best an app password, created in Nextcloud's security settings.

These Nextcloud addresses were checked with Reader's Tasks, Notes and Scanner on the phone and with Reader's Calendar, Tasks, Notes and Scanner on the computer.

### A CalDAV calendar on the phone

Reader's Calendar on the phone has no server settings: it shows the calendars that Android already holds. To see the calendars of a CalDAV server there, install an app that syncs a CalDAV account into the phone's calendars, such as DAVx5, and add your account in it. The calendars then appear in Reader's Calendar and in the agenda tile of Reader's Launcher.

## The credentials file

Several apps can write your server settings into a file, and read them back, so that a second phone or the computer is set up without typing: look for **export credentials** and **import credentials** in the settings or account screen. The same file serves all the apps: each app writes its own part into it and reads only its own part.

The file contains your passwords. Keep it private, send it only to yourself, and delete it once the other device is set up.

## Widgets and tiles

Most Reader's apps provide standard black-and-white widgets that any Android launcher can show. Reader's Launcher has, in addition, its own tiles for the calendar, tasks, notes, the current book, recordings and more. Each chapter's "With the other apps" section lists what the app offers; the launcher's chapter describes every tile.




<!-- The Reader's family -->


# Reader's Installer and Updater

*Android 1.0.2*

## What it is

Reader's Installer and Updater installs the Reader's apps and keeps them up to date. Its list already holds the whole family, plus four other apps by the same author; you tap one, then **Install**, and from then on the installer looks for new versions by itself. Under the phone's app icon it is called **Reader's Installer**.

It is a modified version of Obtainium, drawn in black and white. Everything Obtainium does is still there: any other app can be added from its page on GitHub, GitLab, Codeberg, F-Droid and many other places, with the same options.

It has no account and no tracking. It is not an app store: there are no descriptions, screenshots, ratings or payments, only a list of apps with their versions.

It runs on Android 8.0 and later, phones, tablets and Android TV. The interface exists in 29 languages; in French and some others a few labels remain in English.

## First start

### What the app asks

- **Notifications.** At the very first start Android asks whether the app may send notifications. They tell you that updates are available or were installed. Refusing does not stop the app from working.
- **Installing apps.** The first time you install something, the app shows **Please allow Reader's Installer to install apps** and Android opens its own screen where you allow this source. It is asked once. If you refuse, the installation stops with **Cancelled**.

There is no account to create and no server to enter.

### The welcome message

A box titled **Welcome** reads: "The Reader's apps are in the list. Tap one to install it; installed apps are then kept up to date by themselves. More on the project page:" followed by a link to the project's page. Close it with **Okay**. It is shown once.

### The list fills itself

The catalogue ships with the app. At the first start its 21 apps are added to the list and their latest versions are looked up:

- Reader's Installer and Updater itself;
- Reader's Launcher, Calendar, Tasks, Notes, Books, Bookshop, Recorder, Podcasts, Audio Player, Mindful Tool, Food Log, Scanner, Feeds, Detox, Files and Night Filter;
- ePub Magazine Reader, Le dictionnaire Littré, Clavier Plume and Funky's 2P Games.

At every start the app also reads the current catalogue from the project's page on GitHub, so an app published later appears by itself. Each app is offered once: one you remove from the list is not added back.

Apps you already have on the phone are recognised and show their installed version. The others show **Not installed**.

If the list is ever empty, it shows **No apps**.

## The screens

### Apps

The main screen, titled **Apps**. From top to bottom:

- **The gear**, top right (**Settings**), opens the settings.
- **The search bar** (**Search**). Type part of a name to narrow the list. At its right end:
  - a button showing the number of apps listed: tap it to select them all; when apps are selected it shows how many and a tap clears the selection;
  - a crossed-out funnel, only while a filter or search is active: it removes the filter;
  - the filter button (**Filter apps**), which opens the filter sheet described below.
- **The banner** **Install/update apps** with its button **Update**. It appears when at least two apps are waiting (to be updated or installed) and at least one of them is an update. With apps selected it reads **Install/update selected apps** and concerns only those.
- **The list.** Each row shows the app's icon (pale when the app is not installed), its name, **By** and the author, and on the right the version: **Not installed**, the installed version, or "installed → latest" when an update is waiting. Under the version is the release date; when it is underlined, tapping it shows what changed (a **Changes** box, or the release page in your browser). When an update is waiting, a round download button (**Update**) sits next to the version.
- **Add**, the button at the bottom right, opens **Add app**. While apps are selected it becomes **Actions**.

Apps with a waiting update are placed at the top. Pinned apps are in bold on a shaded row, above the others. An app that belongs to a category carries a stripe of the category's colour on its left edge.

Gestures on the list:

| Gesture | Effect |
|---|---|
| Pull the list down | Checks every app for a new version; a bar shows the progress |
| Tap a row | Opens the app's page |
| Long press a row | Selects it; further taps then add or remove rows from the selection; the back button clears it |
| Swipe a row to the right | Installs the app, or updates it (the row shows **Install** or **Update**) |
| Swipe a row to the left | Asks to remove the app |
| Double tap the icon | Opens the app, if installed |
| Long press the icon | Shows the app's source web page inside the installer; the back button returns to the list |

During a download the right side of the row shows a bar, the percentage, the size and a button to cancel; then **Installing**.

On a screen at least 840 points wide (most tablets in landscape) the list takes the left side and the app's page the right; until you choose an app the right side reads **Select an app to see details**.

On Android TV the bottom-right button is replaced by an **Add app** button at the end of the list, and two buttons at the top: one switches a selection mode on (**Actions**) and off (**Close**), the other is **Refresh**.

### Filter apps

A sheet with:

- **App name**, **Author**, **App ID**: text that must be contained;
- **Up to date apps** and **Non-installed apps**: two switches, both on; switch one off to hide those apps;
- **App source**: **None**, or one of the sources;
- your categories, to keep only the apps of the ones you tick (**No categories** if you have none).

**Continue** applies the filter, **Cancel** leaves things as they were. If nothing matches, the list shows **No apps for filter**.

### Actions

The sheet opened by **Actions** while apps are selected:

- **Remove**: asks to remove the selected apps.
- **Categorize**: puts them in the categories you tick. If they do not all have the same categories, the app first warns: "This will replace any existing category settings for the selected apps."
- **Pin to top**, or **Unpin from top** if one of them is pinned.
- **Install/update selected apps**, when at least one of them can be installed or updated.
- **Share selected app URLs**, **Share app configuration as HTML link**, **Share - Reader's Installer export**: see "Share an app".
- **Download release asset**: for each app, a box titled "Select release asset" asks which file; it is saved to the phone's Download folder.
- **Mark selected apps as updated**: asks "Mark … selected apps as updated?" with the note **Only works for apps with version detection disabled.**; answer **Yes** or **No**.

### The app's page

Opened by tapping a row. Pull it down to check this one app for a new version.

- **Header**: icon, name, **By** and the author. Tapping the icon opens the app if it is installed.
- **Version**: for example "1.4.0 Installed / Latest" when you are up to date, "1.4.0 Installed" and below it "1.5.0 Latest" when an update is waiting, or **Not installed** and the latest version. Under it, the name of the file that will be downloaded, then the date and time of the release (tap it to see the changes when it is underlined).
- **Last update check:** with the date and time, or **Never**.
- **Source**: the address the app is read from (a tap opens it in the browser, a long press copies it) and the app's identifier. For an installed app, the **Certificate Hash** of its signature follows; a long press copies it. Below, **Download release asset** saves a file of the release to the phone's Download folder without installing it.
- **Also on the desktop (Windows, macOS, Linux):** and a link, for the apps that have a computer version (Calendar, Tasks, Notes, Podcasts, Scanner). The link opens in the browser.
- **Categories**: tap a category to put the app in it or take it out; **+** creates a category; a long press on a category edits it.
- The text you may have typed in the app's **About** option.

The bar at the bottom holds, from left to right:

| Button | Effect |
|---|---|
| Pencil (**Additional options**) | Opens the options of this app |
| Gear (**Settings**), only if installed | Opens Android's own settings page for that app |
| Arrow leaving a square (**Open release page**), when the source gives one | Opens the release page in the browser |
| Check mark (**Mark updated**), only when version detection is off for the app | Tells the installer the latest version is the one you have |
| Circular arrow (**Reset install status**), only for an up-to-date app with version detection off or track-only | Marks the app as not installed |
| Bin (**Remove**) | Asks to remove the app |
| **Install** or **Update** | Downloads and installs; the size of the download is written under the label when known |

For a track-only app the main button reads **Mark installed** or **Mark updated**. The main button is grey when the app is up to date or another download is running. During a download a bar with a cancel button appears above the buttons. When it has finished the app shows **Installed** or **Apps updated** and returns to the list.

If the source reports that the project has moved, the page shows **Repository moved** with the **New URL** and two buttons: **Update URL** adopts the new address, **Dismiss** ignores it. Checks for that app are paused until you choose.

### Additional options

Opened with the pencil; the title is "Additional options for" and the app's name. There is no save button: going back saves.

The apps of the catalogue, read from the author's F-Droid repository, have these options:

| Option | Default | What it does |
|---|---|---|
| **App ID or name** | filled in | Which app of the repository this entry follows. Do not change it |
| **Auto-select highest version code APK** | off | Takes the file with the highest internal version number |
| **Try selecting suggested versionCode APK** | on | Takes the version the repository recommends |
| **Track-only** | off | Follows the versions without downloading or installing |
| **Trim version string with RegEx**, **Match group to use for "Trim version string with RegEx"** | empty | Keeps only part of the version text |
| **Reconcile version string with version detected from OS** | on | Version detection: compares with the version Android reports for the installed app |
| **Use release date as version string (pseudo-version)** | off | For apps whose version cannot be detected |
| **Use app versionCode as OS-detected version** | off | Compares internal version numbers instead of version names |
| **Filter APKs by regular expression**, **Invert regular expression (Filter APKs by regular expression)** | empty, off | Chooses among several files |
| **Attempt to filter APKs by CPU architecture if possible** | on | Keeps the files made for your phone's processor |
| **Minimum age for updates** | **Use global default** | Waits this many days before offering a new version: **None**, 1, 2, 3, 5, 7, 14 or 30 days |
| **App name**, **Author** | empty | Replaces the name or author shown in the list |
| **Set Google Play as the installation source (if Shizuku or Root is used)** | off | |
| **Allow insecure HTTP requests** | off | |
| **Expected signing certificate hashes** | empty | Up to four hashes; an update signed otherwise is refused |
| **Exempt from background updates (if enabled)** | off | This app is never installed in the background |
| **Skip update notifications** | off | No notification for this app |
| **About** | empty | A note of your own, shown on the app's page |
| **Refresh app details before download** | off | Checks the version again just before downloading |

Clavier Plume, read from GitHub, has the same options from **Track-only** downwards, and instead of the first three: **Include prereleases**, **Fallback to older releases** (on), **Filter release titles by regular expression**, **Filter release notes by regular expression**, **Verify the 'latest' tag**, **Sort method** (**Release date** by default, **Name (smart)**, **None**, **Name**), **Use latest asset upload as release date**, **Use release title as version string**, **Include ZIP files**, **Filter APKs inside ZIP**, **Include tarball files (tar.gz, etc.)** and **Filter APKs inside tarball**.

### Add app

Opened with **Add**. It serves to follow an app that is not in the catalogue.

- **App source URL**: the address of the app's page (for example its GitHub page). The **+** at the right adds the app once the address is recognised.
- **Search (some sources only)**: type a name and tap the magnifying glass; you tick the sources to search, then pick one result.
- At the bottom, **Supported sources** lists the sources the installer knows (tap one to open its site), and **Crowdsourced app configurations** opens, in the browser, a list of ready-made configurations kept by the Obtainium community.

Once an address is recognised the page shows **Override source** (to force the kind of source, useful for a self-hosted site), a note from the source if any, and the same options as on the **Additional options** page, plus your categories.

### Settings

Opened with the gear. Four rows lead to pages described under "Settings" below: **Import/export**, **Updates**, **Source-specific** and **Appearance**. Four more rows follow:

- **App source** opens the project's page on GitHub in the browser;
- **Based on Obtainium (GPL-3.0)** opens Obtainium's page;
- **Help/wiki** opens Obtainium's help pages;
- **App logs** opens the journal of what the installer did; if there is nothing, it shows **No logs**.

### App logs

The journal of the last seven days, each line with its date and its level (**Info**, **Warning**, **Error**, **Debug**). The text can be selected. The floating bar at the bottom has: two arrows to jump to the top and the bottom, a filter to show only the last 7, 5, 4, 3, 2 or 1 days, **Share** to send the text to another app, and the bin (**Remove**), which asks **Clear logs** ("This will delete all stored logs. Continue?") and confirms with **Logs cleared**.

## How to

### Install an app of the list

1. Tap the app in the list.
2. Tap **Install**.
3. The first time, allow the installer to install apps when Android asks.
4. Confirm in Android's installation box.

You can also swipe the row to the right. If you leave the installer during the download, a notification **Complete app installation** ("Reader's Installer must be open to install apps") calls you back.

### Install several apps at once

1. Long press one app, then tap the others (or tap the number in the search bar to select them all).
2. Tap **Actions**, then **Install/update selected apps**.
3. A box titled "Change" and the number of apps lists them under **Updates** and **Non-installed apps**, each with a tick. Updates are ticked; apps not yet installed are ticked only when there is no update in the box. Tick the ones you want (**Select all** ticks everything) and tap **Continue**.

### Update everything

When the banner **Install/update apps** is shown, tap **Update**, check the ticks and tap **Continue**. Otherwise update one app with the round button on its row, by swiping its row to the right, or with **Update** on its page.

### Check for new versions now

Pull the list down. To check a single app, open its page and pull it down.

### Let updates install themselves

Nothing to do: the installer checks every 6 hours and installs in the background what it can. An update is installed without asking only when all of this holds:

- the phone runs Android 12 or later;
- Android records the app as installed by Reader's Installer;
- the update is a single file;
- the app itself is built for a recent version of Android;
- **Enable background silent installs** is on and the app is not exempt;
- the app is not the installer itself.

In every other case you get a notification **Updates available** ("… has an update."); tap it, then **Update**. The installer's own updates always come this way.

### See what changed in a version

Tap the underlined date under the version, in the list or on the app's page.

### Remove an app from the list, or uninstall it

1. Swipe its row to the left, or tap the bin on its page, or select it and choose **Actions**, **Remove**.
2. The box **Remove app?** has two switches for an installed app: **Remove from Reader's Installer** (on) and **Uninstall from device** (off). Set them as you wish.
3. Tap **Continue**. Android asks you to confirm an uninstallation.

With only the first switch on, the app stays on the phone and simply stops being followed.

### Bring back a catalogue app you removed

1. Tap **Add** and type `https://funkypitt.github.io/fdroid-repo/repo` in **App source URL**.
2. In **Override source** choose **F-Droid third-party repo**.
3. In **App ID or name** type the app's name, for example "Reader's Notes".
4. Tap **+**.

### Add an app that is not in the list

1. Tap **Add**.
2. Paste the address of the app's page into **App source URL**, or search for it.
3. Tap **+**. If the release has several files, **Pick an APK** asks which one; choose and tap **Continue**.
4. The app's page opens: tap **Install**.

From another app (a browser, for instance) you can also share a page to **Reader's Installer**: **Add app** opens with the address filled in.

### Follow an app without installing it

On **Add app** or in the app's **Additional options**, switch on **Track-only**. The installer tells you about new versions; you mark them yourself with **Mark updated**.

### Sort apps into categories

On the app's page, tap **+** under the source, give a **Category name**, pick a **Colour** and tap **Continue**. To put several apps in a category, select them, tap **Actions**, **Categorize**. To show the list by category, set **Group by** to **Category** in **Appearance**. Categories are renamed, recoloured and deleted at the bottom of **Appearance** (tap one) or by a long press on the app's page.

### Pin an app to the top

Select it, tap **Actions**, then **Pin to top**. **Unpin from top** undoes it.

### Share an app

Select one or more apps and tap **Actions**:

- **Share selected app URLs** sends their addresses as text;
- **Share app configuration as HTML link** sends links that open in Reader's Installer on another phone and offer to import the app with its options;
- **Share - Reader's Installer export** sends a file holding these apps.

### Save the list and bring it back

1. **Settings**, **Import/export**, **Pick export directory**: choose a folder.
2. Tap **Reader's Installer export**. The app answers "Exported to" and the folder.
3. On the other phone, **Settings**, **Import/export**, **Reader's Installer import**, and choose the file.

### Change the language, the colours or the size of the rows

**Settings**, **Appearance**: **Language**, **Theme**, **Colour scheme**, **App list density**.

## Settings

### Updates

| Setting | Choices | Default |
|---|---|---|
| **Background update checking interval** | A slider from **Never - manual only**, then 15 minutes, up to 30 days | 6 hours |
| **Enable background silent installs** | on, off | on |
| **Disable background updates when not on Wi-Fi** | on, off | off |
| **Disable background updates when not charging** | on, off | off |
| **Run background update check now** | A button: runs at once what the background check does | |
| **Enable certificate pinning** | on, off. A stricter check of the secure connection to GitHub, Codeberg, GitLab and RuStore | off |
| **Check for updates on startup** | on, off | off |
| **Check for updates on opening an app detail page** | on, off | off |
| **Only check installed and track-only apps for updates** | on, off | off |
| **Global APK filter regex** | Text: a pattern applied to every app that has none of its own | empty |
| **Automatically remove externally uninstalled apps** | on, off. An app uninstalled outside the installer also leaves the list | off |
| **Include pre-releases by default** | on, off. For apps you add | off |
| **Show app downgrade errors** | on, off | on |
| **Hide downgrades as updates** | on, off. A "latest" version older than yours is not offered | on |
| **Skip update/install confirmation dialog** | on, off. **Update** on the banner starts at once | off |
| **Minimum age for updates** | **None**, 1, 2, 3, 5, 7, 14, 30 days | **None** |
| **Allow parallel downloads** | on, off | on |
| **Share new apps with "Verified Apps" (if available)** | on, off. Has an effect only if the Verified Apps app is installed; **About** opens its page | on |
| **Warn about signing certificate changes** | on, off | on |
| **Installation method** | **System**, **Shizuku**, **External app**, **Root** | **System** |
| **Set Google Play as the installation source (if Shizuku or Root is used)** (with Shizuku or Root) | on, off | off |
| **Choose an installer app** (with External app) | The installer apps found on the phone | **None chosen** |

The four settings from **Enable background silent installs** to **Run background update check now** are shown on Android 11 and later (or with the Shizuku method), and only while the interval is not **Never - manual only**.

The little help button on **Enable background silent installs** reads: "Background updates may not be possible for all apps." and "The success of a background install can only be determined when Reader's Installer is opened." The one on **Warn about signing certificate changes** reads: "Before installing, check that the downloaded APK is signed with the same certificate as the installed app. Apps with expected signing certificate hashes configured are always checked."

**Shizuku** and **Root** are for phones set up for them; if the access is not given the method goes back to **System**.

### Appearance

| Setting | Choices | Default |
|---|---|---|
| **Theme** | Three buttons: **Follow system**, **Light**, **Dark** | **Follow system** |
| **Use pure black dark theme** (not with Light) | on, off | on |
| **Colour scheme** | **Standard** (black, white and greys), **Vibrant**, **Expressive**, **Use Material You** (your phone's colours) | **Standard** |
| **Select colour** (not with Material You) | A colour picker with two tabs, **Standard** and **Custom** | grey |
| **App sort by** | **Author/name**, **Name/author**, **As added**, **Release date** | **Name/author** |
| **App sort order** | Two arrows: **Ascending**, **Descending** | **Ascending** |
| **Language** | **Follow system** or one of 29 languages | **Follow system** |
| **Use the system font** (Android 10 and later) | on, off | off |
| **Show source webpage in app view** | on, off. Tapping a row shows the source's web page first; the round button at the bottom (**More**) then opens the app's page | off |
| **Pin updates to top of apps view** | on, off | on |
| **Move non-installed apps to bottom of apps view** | on, off | off |
| **Group by** | **None**, **Category**, **Source** | **None** |
| **Don't show 'track-only' warnings** | on, off | off |
| **Collapse all groups upon startup** | on, off | off |
| **Don't show APK origin warnings** | on, off | off |
| **Highlight less obvious touch targets** | on, off. Shades the version and date you can tap | off |
| **Disable swipe actions on app list** | on, off | off |
| **Always use phone layout** | on, off. No two-pane view on wide screens | off |
| **App list density** | **Standard**, **Compact**, **Minimal (no icon or author)** | **Standard** |
| **Action banner** | **All** (also when only installations are waiting), **Updates**, **None** | **Updates** |
| **Enable tactile feedback** | on, off | on |
| Categories | Your categories as buttons, and **+**; **No categories** when there are none | none |

When the list is grouped, each group has a heading with the number of its apps; tap the heading to fold or unfold it.

### Source-specific

- **GitHub personal access token (increases rate limit)**: optional. Only useful if you follow many apps on GitHub and meet "Too many requests". The catalogue does not need it.
- **'sky22333/hubproxy' instance for GitHub requests**: optional address of a relay for GitHub (the app suggests "gh-proxy.com").
- **Check if repository was moved (increases API calls)**: off by default.
- **GitLab personal access token**, **Codeberg access token**: optional.

The question mark in a field opens the web page that explains how to get the token.

### Import/export

- **Pick export directory**: the folder for exports; a check mark shows it is set.
- **Reader's Installer export**: writes the file now.
- **Automatically export on changes**: off by default. Rewrites an export each time the list changes.
- **Auto-export file name (leave blank for a timestamped name)**.
- **Export installed apps only**: off by default.
- **Include settings**: **None**, **Exclude secrets** (the default), **All**.
- **Reader's Installer import**: reads an export file.
- **Import from URL list**: a page where you paste addresses, one per line, in **App URL list**, or load them with **Import from URLs in file (like OPML)**, then tap **Import**.
- **Import GitHub starred repositories**: asks a GitHub **Username** and offers the projects that person starred.

The last four export settings appear once a folder is chosen.

## Your data

The list of apps, their options, your categories and the settings live on the phone only, in the installer's own storage. There is no account and nothing is sent to the author.

What goes over the network:

- at each start, the catalogue is read from the project's page on GitHub;
- to check and download the catalogue's apps, the installer reads the author's F-Droid repository (hosted on GitHub Pages); Clavier Plume is read from GitHub's releases;
- for apps you add yourself, it contacts the source you gave;
- the links (**App source**, **Help/wiki**, desktop versions, release pages) open in your browser.

Downloaded files are kept in the installer's temporary storage and deleted once installed; unfinished downloads older than seven days are cleared at start. Files saved with **Download release asset** go to the phone's Download folder. The journal keeps seven days.

**Export.** The file is named "obtainium-export-" and the date, ending in ".json". An automatic export ends in "-auto.json", or carries the name you typed, and replaces the previous one. With **Include settings** on **All**, the app warns: "The exported file will contain all settings in cleartext, which may include sensitive values such as tokens. Anyone with the file can read them." With **Exclude secrets**, access tokens are left out.

**Import.** If the file contains apps already in your list, the app asks: "This will overwrite … existing app(s) and replace any settings included in the file. Continue?". Then it reports "Imported … apps", with "+ settings" when the file held settings.

Uninstalling the installer removes its list and settings. The apps it installed stay on the phone, and so do the export files in the folder you chose.

## With the other apps

- This is the app that installs and updates all the others of the family. Each of them can also be installed by other means; the installer recognises an app that is already there.
- It appears in Android's share menu as **Reader's Installer** for text: share a link to an app's page and **Add app** opens with it. If the text has no link, it says "No URL found in shared text".
- Links beginning with `readersinstaller://`, made by **Share app configuration as HTML link**, open in the installer.
- The pages of Calendar, Tasks, Notes, Podcasts and Scanner link to their computer versions.
- It has no home-screen widget.

## Limits

- Android only, version 8.0 or later.
- The installer cannot update itself without your confirmation.
- A background installation is only confirmed for sure when you open the installer; until then a notification may say an app "may have been updated".
- A version older than the one you have is not installed.
- With **External app** as the installation method, an app delivered as several split files cannot be installed.
- The catalogue offers each app once; a removed one comes back only if you add it yourself.
- The search on **Add app** works with some sources only.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **Please allow Reader's Installer to install apps** | Android needs your permission; allow it on the screen that opens |
| **Cancelled** | You refused the permission or closed a box; start again |
| **Complete app installation** / "Reader's Installer must be open to install apps" | A download is ready; come back to the installer |
| **Updates available** / "… has an update." / "… and … more apps have updates." | Tap the notification and update |
| **Apps updated** / "… was updated to …." | Done in the background |
| **App updates attempted** / "… may have been updated to …." | The installer could not confirm; open it to see |
| **Failed to update applications** / "Failed to update … to …." | Update the app by hand from its page |
| **Error checking for updates** | A check failed in the background; the text names the app and the cause |
| **Apps removed** / "… was removed due to this error: …" | An entry could not be read and was taken off the list |
| "Too many requests (rate limited) - try again in … minutes" | The source limits the number of requests; wait, or add a token in **Source-specific** |
| **No APK found**, **Could not find a suitable release**, **Could not determine release version** | The source has no file the installer can use for this app |
| **App already added** | The app is in your list already |
| **URL does not match a known source**, "Not a valid … app URL" | The address is not an app page the installer understands |
| "… needs additional credentials (in Settings)" | The source wants a token; see **Source-specific** |
| **Download failed**, "Error" followed by a number | The download did not go through; try again later |
| **The APK could not be parsed (incompatible or partial download)** | The file is damaged or not made for this phone; try again |
| **Cannot install an older version of an app** | The version offered is older than yours |
| **Downloaded package ID does not match existing app ID** | The file is not the app expected; do not install it |
| **Signing certificate mismatch**: "… is signed with a different certificate than the installed version. Installing it will most likely fail. Only continue if you trust this source." | The update is not signed like your copy. **Don't install** stops; **Install anyway** tries |
| "The downloaded file for … does not match the signing certificate hash you configured. The install has been blocked." | Applies to apps where you filled in **Expected signing certificate hashes** |
| **Install confirmation was not received in time — the app may not have been installed** | Check the app's version, and install again if needed |
| **Warning**: "The app source is '…' but the release package comes from '…'. Continue?" | The file is hosted elsewhere than the app's page; **Don't show this again** silences the warning |
| "App is track-only" / "The app will be tracked for updates, but Reader's Installer will not be able to download or install it." | You chose **Track-only**, or the source only allows that |
| **The latest release is younger than the minimum update age (… days) and this source does not provide older releases.** | Caused by **Minimum age for updates**; wait or lower it |
| **Choose an external installer in Settings first** | **External app** is chosen but no app is picked |
| **Root access was not granted**, **Dhizuku or Shizuku services are not running**, **Old Shizuku version (<11) - update it** | The installation method you chose is not available; the method returns to **System** |
| **No file picker available. Please install a file manager app.** | Android found no app to choose a file or folder |
| **Invalid input**, **Invalid regular expression** | A field holds something the app cannot use |
| **Import errors**: "… of … apps imported." and **The following URLs had errors:** | Some addresses could not be added; each is listed with its reason |
| **A category with this name already exists** | Choose another name |
| **Some errors occurred** | A box listing, for each cause, the apps concerned; a long press copies the text |
| **An unexpected error occurred.** with **Close** | The app could not draw a screen; close and reopen it |

If an app keeps showing **Not installed** or a wrong version although it is on the phone, pull the list down. An app imported from a list of addresses may show "not installed" wrongly; installing it again through the installer puts this right and does not touch its data.


# Reader's Launcher

*Android 1.19.0 (Android 8.0 or later)*

## What it is

Reader's Launcher is a home screen for Android made of words only: black and white, no icons, no colours, no wallpaper. Each home page is a fixed column of tiles that never scrolls: app names, categories (a name that opens a list of apps), and text widgets such as the clock, the weather, the next event or the first task. A small grid of key apps can sit at the bottom, and a book or a reading app waits on each side of the home screen, one swipe away.

It deliberately has no icons (except the monochrome glyphs of the grid and of the weather), no wallpaper, no folders with pictures, no account and no tracking. It never talks to a calendar or task server itself; only the weather tile uses the network.

The app follows the language of the phone: English, French, German, Spanish, Portuguese or Russian.

## First start

The first time, the page is empty and shows **hold to begin** in its middle. A long press anywhere opens the menu from which you add your first tile.

As long as Reader's Launcher is not the phone's home app, a line **set as default launcher** stays at the top of the home screen. Tap it: Android's home-app settings open, where you choose Reader's Launcher. The line disappears once this is done.

There is no account and no server to enter. Permissions are asked only when a function needs them:

| Permission | Asked when | What it is for |
|---|---|---|
| Approximate location | you add the **weather** tile | the weather of the place where you are; you can refuse and choose a city instead |
| Calendar (read) | you add or tap the **agenda** tile | showing your next events |
| Tasks.org tasks (read and write) | you choose Tasks.org in **tasks setup** | showing, ticking and adding tasks |
| Usage access (a special access given in Android's settings) | you open **open apps**, or **usage access (open apps list)** in the settings | the list of recently used apps |
| Placing a widget | you add a widget **from apps** | Android may ask you to allow each widget |

The launcher also lists the installed apps, opens the notification shade, vibrates lightly on long presses and can ask Android to uninstall an app; none of these shows a prompt. The other Reader's apps (Tasks, Books, Notes, Mindful Tool, Recorder, Night Filter) are read without any prompt.

## The screens

### The home screen

A home page is a column of tiles on a fixed grid of cells. An app or category name takes 2 cells, a two-line widget 3, the clock or the weather 4, a widget from another app the height you give it. When the cells are used up nothing more can be added to that page.

Under the tiles, if you have more than one page, a row of dots shows where you are (● for the current page, ○ for the others). At the very bottom, the grid of key apps, if you added one, is the same on every page.

Gestures on the home screen:

| Gesture | Effect |
|---|---|
| tap an app name | opens the app |
| tap a category name | opens its list of apps |
| double tap an app name or a grid square | lists the app's shortcuts |
| long press a tile | the tile's menu |
| long press on empty space | the home menu |
| double tap on empty space | flips between white on black and black on white |
| swipe up | the list of all apps |
| swipe up and hold | **open apps**, the recently used apps |
| swipe down | the notification shade |
| swipe left | the next home page; past the last one, the right side (book or reading app) |
| swipe right | the previous home page; before the first one, the left side (book or reading app) |
| the phone's Home button | back to the home screen from any screen of the launcher |

Several tiles use the sideways swipe for themselves (agenda, tasks, book, notes, recordings, mindful): to change page, swipe on another part of the screen.

### The home menu

A long press on empty space shows:

- **add app / category**: choose one or several apps (see "Add an app" and "Make a category").
- **add app grid**: adds the grid of key apps at the bottom (shown only while there is no grid).
- **add widget**: opens the widget list.
- **add a home page**: adds an empty page after the last one and goes to it.
- **remove this page**: shown on an empty page other than the first.
- **black on white** or **white on black**: switches to the other theme.
- **settings**.

When the page has no room left for a line of text, **the home screen is full** replaces **add app / category** and **add widget**.

The same entries are repeated, in smaller text, at the bottom of every tile's menu, because a full page has no empty space left to press.

### A tile's menu

A long press on a tile shows its name and, depending on the tile:

- **open**: opens the app or the category.
- **shortcuts** (app): the app's shortcuts, with **open** below them; **no shortcuts** when it has none.
- **edit** (category): the category's edit screen.
- **rename** (app, category).
- **configure** (tasks, mindful, some widgets from apps), **choose calendars** (agenda).
- **height: 3** (widget from an app): each tap adds one cell, from 2 to 8, then starts again at 2.
- the weather entries (see "The weather tile").
- **move up**, **move down**.
- **move to the next page**, **move to the previous page**, when such a page exists.
- **arrange tiles**, when the page has more than two tiles.
- **app info**: Android's page for the app.
- **uninstall**: for apps that are not part of the system.
- **remove**: takes the tile off the home screen (the app itself stays installed).

### The list of all apps (apps)

Swipe up. The screen **apps** lists every app alphabetically, with a **search** field already active: type a few letters (accents do not matter), and the keyboard's action key opens the first result. Apps of a work profile carry the word **work** under their name. Tap the title line (←) to go back.

Tap an app to open it. Long press it for:

- **open**, **shortcuts**;
- **add to home**: adds its name to the page you were on (not shown if it is already on a home page);
- **add to category**: then choose the category (shown when you have at least one);
- **add app grid**: puts the app in the first free square of the grid (shown when the grid has a free square);
- **rename**: the name shown everywhere in the launcher; type the original name again to drop the change;
- **hide**: removes it from this list;
- **app info**, **uninstall**.

The same list serves to choose apps: titled **choose apps** (tap to select, the title then reads **tap to select · 2 selected**, and **add** at the top right confirms) or **choose an app** (one tap chooses). In these lists hidden apps are shown too.

### A category

Tap a category name: its apps appear as a list, with **edit** at the top right. Tap an app to open it, double tap for its shortcuts, long press for **open**, **shortcuts**, **remove from category**, **app info**, **uninstall**. An empty category shows **add apps**.

The edit screen offers **rename**, **add apps** (the app list with the current apps already selected; deselect one to take it out), and the list of apps under **drag a tile to move it**: long press a line and drag it to reorder; tap a line for **remove from category**.

### The grid of key apps

A row of 3 to 5 squares at the bottom of every page, for the apps you cannot do without. Each app appears as a monochrome glyph of its icon; an empty square is a dot.

- Tap a filled square to open the app; double tap for its shortcuts.
- Tap an empty square, or long press any square, for its menu: **add app / category** (here it picks a single app for that square), or, on a filled square, **open**, **shortcuts**, **change app**, **clear**, **app info**; then **squares: 5** (each tap changes the number: 5, 3, 4, 5…) and **remove** (removes the whole grid).

### Add widget

The list has two parts.

**built in**:

| Widget | What the list says |
|---|---|
| **clock** | time and date |
| **weather** | time and today's weather, tap for five days |
| **mot du jour** | the Littré's word of the day, tap for the definition |
| **book** | the book you were reading, tap to carry on |
| **notes** | the latest note, swipe for the others, + writes one |
| **recorder** | record with one tap (Reader's Recorder); the latest recording under it |
| **recordings** | listen to Reader's Recorder's recordings, swipe from the latest to the older ones |
| **food log** | one touch opens Reader's Food Log's viewfinder for a new photo |
| **night filter** | the screen gray, warm and dim: Reader's Night Filter on and off |
| **mindful** | a bowl every X minutes and a timed meditation, started and stopped here (needs Reader's Mindful Tool) |
| **agenda** | next event, swipe for the following ones |
| **tasks** | first task of a list, swipe for the following ones |

**from apps**: every widget offered by the apps installed on the phone, with a **search** field. Tap one; Android may ask you to allow it, and the widget may open its own setup screen. If it does not fit in the cells left, it is refused with **the home screen is full**.

### The clock tile

The time in large figures (12 or 24 hours, as the phone is set) and the date under it. Tap it to open the alarms of the phone's clock app.

### The weather tile

The time on the left; on the right a weather glyph, the current temperature and the day's minimum / maximum; the place name under the time (**here** when it has no name). Tap to switch between today and five days (day, glyph, maximum/minimum). The forecast is refreshed every half hour.

Its menu adds:

- **source: MétéoSuisse** or **source: Open-Meteo** (information only);
- **refresh**;
- **units: °C** (tap for °F and back);
- **location: automatic**, with **choose a city** under it: tap to type a **city name**; the first place found is used;
- when a city is set, **location: (the city)** to change it, and **use automatic location**.

### The agenda tile

Two lines: the title of an event, then when it takes place (**today**, **tomorrow**, the weekday or the date, the hours or **all day**), followed by its rank such as 2/7 when there are several.

- Tap: opens the event in the calendar app. If there is no event, a page **agenda** opens instead, with **open the agenda**, **+ new event**, and the events of **today** and **tomorrow**.
- **+** at the right: creates an event in the calendar app.
- Swipe left for the next event, right for the previous one.

The tile chooses by itself which event to show first: an event with hours takes the place from one hour before it starts until it ends; otherwise today's all-day event is shown; otherwise the next thing to come. It looks one year ahead.

Its setup screen (when you add the tile, or **choose calendars** in its menu) has two lists. Under **opens with**: the calendar apps of the phone, Reader's Calendar first and chosen by default when installed, and **whatever the system picks**. Under **calendars to show**: every calendar of the phone with its account; tap to select or deselect (all are selected for a new tile). Confirm with **ok** at the top right.

### The tasks tile

A box ☐, the title of the first open task, and under it the name of the list and the rank (1/4). 

- ☐ completes the task.
- **+** opens the prompt **new task**; **add** creates it in the list.
- Swipe left for the next task, right for the previous one.
- Tap the text: opens the tasks app.

The tile refreshes as soon as the tasks app changes something.

### The mot du jour tile

The word of the day of the dictionary app Le Littré, with **mot du jour** under it. Tap for the definition on a page of its own, with **open in Le Littré** at the bottom. If Le Littré is not installed the tile reads "Le Littré" and a tap opens the app's web page.

### The book tile

The title of the book you last opened in Reader's Books, with **book**, its rank and the percentage read under it. Swipe left for the books opened before it, right to come back. Tap to carry on reading in Reader's Books. With an empty shelf the tile reads **open a book**.

### The notes tile

The title of the latest note of Reader's Notes (**untitled** if it has none), and under it **notes**, the rank and the beginning of the text. Swipe sideways through the thirty most recent notes; tap to open the note; **+** writes a new one. Without any note: **no note yet**.

### The recorder tile

**record** with a ● at the right, and the latest recording (title and length) under it. Tap ● to start: the tile reads **recording · 00:12** and **tap ■ to stop**; ■ stops. **paused** replaces **recording** while Reader's Recorder is paused. Tap the text to open the latest recording in Reader's Recorder (or the app itself while recording).

### The recordings tile

One recording of Reader's Recorder: its title, and under it **recordings**, the rank, the date and the length. ▶ plays it without leaving the home screen (❚❚ pauses; the line then shows position / length). Swipe left for older recordings, right for more recent ones. Tap the text to open the recording. Without any: **nothing recorded yet**.

### The food log tile

**photograph**, with **food log** under it and ◉ at the right. One touch opens the viewfinder of Reader's Food Log for a new photo.

### The night filter tile

**filter on** or **filter off**, with a switch at the right (● on, ○ off) that turns Reader's Night Filter on and off. Tap the text to open the app. When the caption reads **one step left in the app**, the filter still lacks an authorisation: the app opens and explains it.

### The mindful tile

Two functions of Reader's Mindful Tool: **a bowl every 10 min** and **meditate 20 min**. When you place the tile you choose **both** (swipe sideways to go from one to the other), **a bowl every X minutes only** or **meditation period only**; **configure** in the tile's menu changes this choice.

- Tap the words to change the minutes (**a bowl every how many minutes?**, **meditate how many minutes?**; from 1 to 240).
- ▶ starts, ■ stops.
- While bowls are running: **next at 14:30 · in 04:12**, then the number already **rung**.
- While a meditation is running: **until 14:50 · 12:40 left** and a thin progress line. A tap on the words then opens the app.

### Widgets from other apps

They show and work as on any home screen. A long press opens the launcher's tile menu, where **height** sets how many cells the widget takes and **configure** reopens the widget's own setup if it has one.

### Open apps

Swipe up and hold your finger still for a moment. **open apps** lists up to twelve apps used in the last six hours, the most recent first. Tap to go to one; long press for its Android info page. Without the authorisation, the line **allow usage access to list open apps** leads to Android's setting. With nothing to show: **no recent apps**.

### Arrange tiles

From a tile's menu or from the settings. The tiles of the page are listed by name (widgets with a dash in front), under a count such as **7 of 16 cells in use** and the hint **drag a tile to move it**. Long press a line, then drag it to its new place. With several pages, the line **page 1 of 2** / **tap for the next page** changes page.

### Hidden apps

In the settings. Lists the apps you hid; each line carries **show again**: tap it to bring the app back in the list of all apps. Empty: **nothing here**.

### A side of the home screen: the book

Swipe right on the first page for the left side, left on the last page for the right side.

An empty side shows:

- **open a book** (**epub, mobi, fb2 or plain text**): tap anywhere to choose a file.
- **or a reading app**: Kindle, Kobo… opened by the swipe instead of a book kept here.
- on the right side only, **or a second home page**: another page of tiles here instead of a book; the book slot then sits after the last page.
- **swipe sideways to go back home**.

With a book, the page shows the title at the top, the text, and at the bottom the chapter name, the page within the chapter and the percentage of the book (3/12 · 41%).

| Gesture | Effect |
|---|---|
| tap the right half | next page |
| tap the left half | previous page |
| long press | the reader's menu |
| swipe sideways, or Back | return to the home screen |

The reader's menu: **chapters** (the list of chapters, the current one highlighted; tap one to go there), **larger text** and **smaller text** (two points at a time, between 12 and 40; the menu shows the change, for example 20 → 22), **open another book**, **remove from this side**, **home**.

The book reopens where you stopped. The screen stays on while you read and is released after 15 minutes without a page turn. The reader uses the launcher's theme and font.

### Settings

Long press, then **settings**. Described under "Settings" below.

### Restore a backup

Shown after you choose a backup file. See "Move the home screen to another phone".

## How to

### Add an app to the home screen

1. Long press on empty space (or on any tile), then **add app / category**.
2. Tap the app; its line is highlighted.
3. Tap **add** at the top right.

Or: swipe up, long press the app, **add to home**.

### Make a category

1. Long press, **add app / category**.
2. Tap several apps.
3. Tap **add**, type the **name of the category**, then **add**.

To change it later: long press the category, **edit** (add, remove, reorder apps) or **rename**. To put one more app in it from the list of all apps: long press the app, **add to category**.

### Add a widget

1. Long press, **add widget**.
2. Tap a widget under **built in**, or one **from apps**.
3. Answer the setup screen if one appears (agenda, tasks, mindful, some widgets from apps).

### Move, reorder or remove a tile

- One step: long press the tile, **move up** or **move down**.
- Freely: long press the tile, **arrange tiles**, then long press a line and drag it.
- To another page: long press the tile, **move to the next page** or **move to the previous page**.
- Remove: long press the tile, **remove**.

### Add or remove a home page

- Add: long press, **add a home page**. Or, on the empty right side, **or a second home page**.
- Remove: empty the page (move or remove its tiles), long press on it, **remove this page**. The first page cannot be removed.

### Set up the grid of key apps

1. Long press, **add app grid**.
2. Tap a square, **add app / category**, choose the app.
3. To change the number of squares, long press a square and tap **squares: 5** until it suits you.

### Rename, hide or uninstall an app

- Rename: long press its tile, **rename**; or in the list of all apps, long press, **rename**.
- Hide: swipe up, long press the app, **hide**. To bring it back: settings, **hidden apps**, tap the app.
- Uninstall: long press the app (tile or list), **uninstall**; Android asks for confirmation.

### Switch between white on black and black on white

Double tap on empty space; or long press and tap **black on white** / **white on black**; or use the quick-settings tile **Reader's theme** (add it to Android's quick-settings panel by editing the panel); or the **theme** line in the settings.

### Set up the weather

1. Long press, **add widget**, **weather**. Accept the location request for the weather of where you are.
2. To use a fixed city instead: long press the tile, tap **location: automatic** (choose a city), type the **city name**, **ok**.
3. For Fahrenheit: long press the tile, **units: °C**.

### Set up the tasks tile

1. Long press, **add widget**, **tasks** (or settings, **tasks setup**, which also adds a tasks tile).
2. Tap **Reader's Tasks** or **Tasks.org**. One marked **not installed** opens its download page instead.
3. For Tasks.org, accept the access request (or tap **allow access to tasks**).
4. Under **choose a list**, tap the list. The tile is placed.

To change the list of a tile: long press it, **configure**.

### Show only some calendars in the agenda

Long press the agenda tile, **choose calendars**, tap the calendars to select or deselect, choose the app under **opens with**, then **ok**.

### Read a book beside the home screen

1. Swipe to an empty side and tap **open a book**, then choose the file.
2. Or, from a file manager or another app, open or share an ebook with Reader's Launcher: a menu **open a book** asks **left of the home screen** or **right of the home screen**.

To replace it: long press in the reader, **open another book**. To empty the side: **remove from this side**.

### Open Kindle, Kobo or another reading app with the swipe

1. Settings, **left of the home screen** or **right of the home screen**.
2. Tap **a reading app…** and choose the app. (On an empty side, **or a reading app** does the same.)
3. For Kindle, to open one book directly: tap the same settings line again, **the Kindle book to open…**, and paste the book's link (Share in Kindle or Amazon) or its ASIN. **open Kindle only** cancels this.

To go back to a book kept in the launcher: the same line, **a book kept in the launcher**. The book that was there has not moved.

### See the recently used apps

Swipe up and hold. The first time, tap **allow usage access to list open apps** and allow Reader's Launcher in Android's list.

### Move the home screen to another phone

1. On the first phone: settings, **back up the home screen**. Android's share sheet opens; send or save the file (readers-launcher-backup.json).
2. On the other phone: settings, **restore a backup**, choose the file.
3. The page shows when the backup was made, its pages and tiles, and **it replaces the home screen and the look of this phone**. Under **not on this phone — tap for its store page** are the apps the backup uses and this phone lacks, each with where it was (**on the home screen**, **in the grid**, **widget**, **in** a category); tap one to install it first. **widgets not available on this phone** lists widgets whose app is there but no longer offers them. If nothing is missing: **every app of this home screen is on this phone**.
4. Tap **restore** (or **restore anyway** if something is missing), or **cancel**.

After **home screen restored**, widgets from apps are placed again one by one; Android may ask to allow each. A widget not yet placed stays as a line **place the widget**: tap it to try again.

## Settings

Each line shows its current value; a tap moves to the next one.

| Setting | Choices | Default |
|---|---|---|
| **theme** | **white on black**, **black on white**, **follow system** | white on black |
| **font** | **serif**, **sans**, **mono** | sans |
| **text size** | **small**, **medium**, **large** | medium |
| **alignment** | **left**, **center** | left |
| **double tap flips theme** | **on**, **off** | on |
| **swipe down opens notifications** | **on**, **off** | on |
| **status bar** (shown or hidden on the launcher's screens) | **on**, **off** | on |
| **haptic feedback** (a light vibration on long presses and swipes) | **on**, **off** | on |
| **auto-rotate** (off keeps the launcher upright) | **on**, **off** | off |
| **double tap on an app shows its shortcuts** | **on**, **off** | on |

With **double tap on an app shows its shortcuts** on, a single tap on an app waits a short instant to see whether a second tap follows; turn it off for an immediate opening (the shortcuts stay in the long-press menu).

Then:

- **arrange tiles**, **hidden apps**, **tasks setup**: the screens described above.
- **left of the home screen**, **right of the home screen**: what the swipe to that side opens. The line shows the reading app (and the Kindle book), or the title of the book, or **a book kept in the launcher**.
- **default launcher**: Android's home-app settings.
- **usage access (open apps list)**: Android's usage-access settings.
- **back up the home screen** (a file for another phone: pages, tiles, apps, look — no password) and **restore a backup**.
- **reader's launcher 1.19.0**: tap for the line **black and white, text only. MIT licence.**

Settings kept on the tiles themselves: weather units and place, agenda calendars and app, task list, mindful mode and minutes, widget height. The reading text size is set in the reader's menu and applies to both books.

## Your data

Everything stays on the phone: the pages and tiles, the settings, the hidden apps and custom names, the books you opened (each is copied into the launcher's own storage, so it keeps working if the original file is moved or deleted) and the place you reached in them.

The network is used by the weather tile only. It sends the coordinates of the place (your approximate position, or the chosen city) to Open-Meteo; for a place in Switzerland it first asks the Swiss federal map service (geo.admin.ch) for the postal code, then MeteoSwiss for the forecast, and falls back on Open-Meteo if that fails. A city name you type is sent to Open-Meteo's place search, with the phone's language. No key, no account, no identifier. The last forecast is kept on the phone.

Events, tasks, notes, books, recordings and the word of the day are read on the phone from the apps that hold them; the launcher never contacts their servers.

The backup file contains the pages and tiles with their settings, the categories, the grid, the hidden apps, the custom names, the look (theme, font, sizes, gestures), the name of each app used, and the calendars of each agenda tile by name. It contains no password. It does not contain the books, the reading positions, the choice of a reading app for the sides, or the weather. On restore, calendars are found again by account and name (all calendars if none matches) and task lists by their title.

Uninstalling Reader's Launcher removes the home screen layout, the settings and the copies of the books. The other apps and their data are not touched.

## With the other apps

- **Quick-settings tile**: **Reader's theme** flips the launcher between its two themes from Android's quick-settings panel.
- **Reader's Tasks** or **Tasks.org**: the tasks tile. With Tasks.org 15.11 or later, tasks are ticked and added on the tile; with an older version the box opens the task in Tasks.org and **+** opens Tasks.org with the title filled in.
- **Reader's Calendar** (or any calendar app): the agenda tile reads the phone's calendars and opens events in the chosen app.
- **Reader's Books**: the book tile.
- **Reader's Notes**: the notes tile.
- **Reader's Recorder**: the recorder and recordings tiles.
- **Reader's Mindful Tool**: the mindful tile.
- **Reader's Food Log**: the food log tile.
- **Reader's Night Filter**: the night filter tile.
- **Le Littré**: the mot du jour tile.
- **Kindle, Kobo or any reading app**: opened by the swipe to a side.
- **Ebook files**: Reader's Launcher appears in "open with" and in the share menu for EPUB, MOBI (and Kindle AZW in "open with") and FB2 files.
- **Widgets of any app**: placed as tiles.

A tile of a Reader's app that is not installed shows that app's name in dim text (the mindful tile reads **Reader's Mindful Tool is not installed**); a tap opens the app's web page.

## Limits

- Android does not let a launcher replace the system's recent-apps view; **open apps** is a list of recently used apps, without previews, and without the apps of a work profile.
- A page never scrolls: what does not fit goes on another page. The cell count in **arrange tiles** tells how much room is left.
- The reader shows text only: no images, no footnote links, no styling. Formats: EPUB, MOBI/PRC/AZW without protection (compressed the usual PalmDoc way or not at all), FB2, plain text. No PDF. Books with DRM and Kindle-store files in the newer compression are refused.
- One book per side, two in all.
- The Kindle link that opens one book is Kindle's own, not a documented one: if Kindle stops answering it, the app alone opens.
- An app's shortcuts are available only while Reader's Launcher is the default launcher.
- The agenda tile holds at most the 60 next events of the coming year; the tasks tile the 50 first open tasks (sub-tasks are not shown); the notes tile the 30 latest notes.
- A city is chosen by name and the first match is taken: add the country if the wrong one comes up.
- The widget **mot du jour** keeps its French name in every language.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **set as default launcher** | Reader's Launcher is not the home app yet. Tap the line and choose it. |
| **hold to begin** | The page is empty: long press to add something. |
| **an empty page — hold to add something, or remove it** | A further page with nothing on it. |
| **the home screen is full** | No cells left on this page. Remove a tile, lower a widget's **height**, or add a home page. |
| **could not add this widget** | Android could not open its request to place the widget. Try again. |
| **widget app was removed** | The app that provided this widget is gone or no longer offers it. Long press the line, **remove**. |
| **place the widget** | A widget from a restored backup is not placed yet. Tap the line and allow it. |
| **no location — hold to choose a city** | The weather has no position. Tap to allow location (or to type a city if location is allowed but unknown), or long press and choose a city. |
| **weather unavailable** | The forecast could not be fetched (no network). Tap to try again. |
| **…** | Loading. |
| **allow calendar access** | The agenda cannot read the calendars. Tap and allow. |
| **no upcoming event** | Nothing in the chosen calendars for the coming year; check **choose calendars**. |
| **(untitled)** | An event without a title. |
| **set up tasks** | The tasks app is missing or access was not given. Tap to open **tasks setup**. |
| **allow access to tasks** | Tasks.org has not yet allowed the launcher. Tap and accept. |
| **tasks unavailable** | The list could not be read from the tasks app. Check in **tasks setup** that the app and the list are still there. |
| **no open task** | The list has no task left to do. |
| **no list found — create one in the tasks app first** | The tasks app has no list yet. |
| **choose a list. With this version of Tasks.org, the box opens the task and + opens Tasks.org. From version 15.11 you can tick and add tasks right here.** | Your Tasks.org is older than 15.11: update it to tick and add from the tile. |
| **not installed** | That tasks app is not on the phone; tap to get it. |
| **Reader's Mindful Tool is not installed** | The mindful tile needs that app; tap to open its page. |
| **one step left in the app** | Reader's Night Filter still needs its authorisation; open it and follow its instructions. |
| **allow usage access to list open apps** | Tap, then allow Reader's Launcher in Android's usage-access list. |
| **no recent apps** | No app was used in the last six hours. |
| **no shortcuts** | The app offers none, or Reader's Launcher is not the default launcher. |
| **nothing here** | No app matches the search, or no app is hidden. |
| **app not found** | The app of this tile is no longer installed. Remove the tile. |
| **cannot open** (the app) | Android refused to start the app. |
| **cannot open the shortcut** | The shortcut is no longer valid. |
| **this file could not be read** | The file is not a book the reader understands, or it is protected. Tap to choose another. |
| **no ASIN found in that** | What you pasted is neither a Kindle or Amazon book link nor a ten-character ASIN. |
| **not a Reader's Launcher backup** | The chosen file is not a backup of this app. |
| **this backup comes from a newer Reader's Launcher (format 2): update the launcher first** | Update the app, then restore again. |
| **home screen restored** | The restore is done. |


# Reader's Calendar

*Android 1.15.2 · Windows, macOS, Linux 1.14.3*

## What it is

Reader's Calendar is a calendar in black and white, made of text only: agenda, month, week, workdays and day. The calendar an event belongs to is named in words; colour is an option, never a code you have to learn.

It comes as two programs. On an Android phone it shows and edits the calendars the phone already holds, the ones your accounts sync (Google, Infomaniak, DAVx⁵, Nextcloud…): it has no account and no network access of its own. On a computer (Windows, macOS, Linux) it connects by itself to your calendar server with CalDAV, to a Google account through an access you create yourself, and to read-only calendar addresses (feeds).

It deliberately leaves out invitations and guests, time zones other than your own, and alerts: a reminder is stored with the event, but neither program rings or shows a notification itself.

Both programs speak English, French, German, Spanish, Portuguese and Russian, following the language of the device.

## First start

### On the phone

At the first start Android asks for access to the calendar. The app needs it to read your events and to write the ones you create or change. It asks for nothing else, and it has no permission to use the network.

If you refuse, the agenda shows the row **allow access to the calendars**; tap it to be asked again.

There is no account to enter. The calendars shown are the ones the phone already syncs. If the phone holds none, or nothing is planned in the coming days, the agenda says **nothing planned**.

The app opens on the week. Go back once to reach the agenda.

### On the computer

At the first start a dialog asks for your accounts. You can fill in one, two or all three parts, then press **connect**.

| Field | What to put |
|---|---|
| **server** | The address of your CalDAV server. The app gives the example of Infomaniak: `https://sync.infomaniak.com`. Nextcloud, Radicale and other servers work too. |
| **username** | Your login on that server. For Infomaniak, a login of the form `AB12345`. |
| **app password** | Your password; an application password if two-factor authentication is on. |
| **feeds** | Read-only calendars, one per line, written as a name, the sign `\|`, then the address. The address ends in `.ics` or starts with `webcal`. For Google Calendar: the calendar's settings › Integrate calendar › Secret address in iCal format. |
| **client ID**, **client secret** | Only for a Google account in read and write: the two values of an access (an "OAuth client") you create yourself at Google. See "Connect a Google account" below. |
| **Google account** | The button **connect the Google account**, and next to it the state of the connection. |

The dialog also holds **import credentials…** and **export credentials…** (see "Your data"), and **cancel**.

If you cancel without any account, the bottom of the left column says **not connected — Ctrl+, to set up**. Ctrl+, or the ⚙ sign reopens the settings, where every row under **accounts** opens this dialog again.

While it works, the bottom of the left column says **connecting…**, then **syncing…**, then **synced** followed by the time.

## The screens

### Phone: the ⋯ menu

Every view has a **⋯** sign at the top right. It opens the same menu everywhere:

- **today**: back to the current week, month or day (shown in the week and the month, and in the day view when another day is displayed);
- **+ new event**;
- **today (list)**: the agenda;
- **today (day view)**: today as a time grid;
- **week**;
- **workdays**;
- **month**;
- **calendars**;
- **black on white** or **white on black**: switches the colours at once;
- **settings**.

Tap outside the menu to close it. On every screen except the agenda, the title at the top left starts with **←**: tap it, or use the phone's back gesture, to go back.

Every view ends with the row **+ new event**.

### Phone: agenda

The coming days as a list, grouped by day. Each day has a heading (**today · …**, **tomorrow · …**, then the date). Each event shows its title and, under it, its hours (or **all day**) and its place.

- Tap an event: its page.
- Tap a day heading: that day as a time grid.
- Long press a day heading: a new event on that day.
- Tap the title (the month and year, followed by ▾): the month view.
- **show more days**, at the end of the list: 60 more days. The list starts with 60 days.

With the phone held sideways, the agenda takes the right side. The left side shows the month as a grid of numbers (a dot marks the days that hold something, today is inverted), then **week** and **workdays**. Tap a day in the grid for that day, long press it for a new event, tap the month's name for the month view.

### Phone: month

Six weeks that fill the screen. Each day shows its number and its events, one line each, all-day events first. When a day is full, **+2** (or another number) tells how many more there are. Today's number is inverted; the days of the neighbouring months are dimmed. On a wide screen the lines start with the hour.

- Tap a day (or an event line): that day as a time grid.
- Long press an empty part of a day: a new event on that day.
- Swipe sideways: the next or previous month.
- Long press an event line, then drag it to another day: the event moves there. The day under your finger is framed.

### Phone: week and workdays

A time grid: one column per day, the hours down the side. Events are solid blocks, so the gaps between them read as free time. Events that overlap sit side by side. All-day events are in a strip above the grid. Today's heading is inverted and a line marks the present moment.

- Tap a block: the event's page.
- Tap an empty slot: a new event at that hour, one hour long.
- Tap a day heading: that day alone.
- Swipe sideways: the next or previous week.
- Long press a block, then drag: the event moves, by quarter hours up and down and by whole days sideways. The block shows its new hours while you drag; the grid scrolls when your finger nears its top or bottom.

**workdays** shows Monday to Friday at full width. Saturday and Sunday are folded into a narrow strip at the right: one letter per day, and a dot when the day holds something. Tap the strip for the whole week.

### Phone: day

The same grid, one column wide. Each block shows the title, the hour and the place. Swipe sideways for the next or previous day. Taps, long presses and drags work as in the week.

### Phone: event

The page of one event: title, date, hours (or **all day**), the repetition, the reminder, then the calendar it belongs to and its account, the place and the description.

The place and the description are live text:

- a phone number opens the dialer with the number ready (it is never dialled by itself);
- a mail address opens the mail app;
- a web address opens the browser;
- the place opens the maps app.

Long press anywhere to select and copy text. Dates, prices and room numbers stay plain text.

At the bottom: **edit** and **delete**. For an event of a calendar you cannot write to (one shared with you for reading, public holidays…), the line **this calendar is read only: its events cannot be changed here** takes their place: such an event cannot be edited, deleted or moved from the app.

### Phone: new event and edit

The form is titled **new event** or **edit**. **save** is at the top right and at the bottom.

| Row | What it does |
|---|---|
| **title** | Opens a prompt to type the title. For a new event it opens by itself, keyboard up. |
| the date, marked **starts** | Opens a month grid; **‹** and **›** change the month; tap a day. Moving the start keeps the event's length. |
| the hours, marked **start time · end time** | Asks the start, then the end, in two prompts. Type digits: `1830`, `18.30`, `18h30` or `930` are all understood. Changing the start keeps the event's length. |
| **all day: off** / **all day: on** | Tap to switch. |
| **ends another day** | Opens the month grid for the end date. Once the end is another day (or the event lasts all day), a row marked **ends** shows it. |
| the calendar, marked **calendar** and its account | Lists the calendars you may write to. |
| **reminder** | **no reminder**, **at the time of the event**, **10 minutes before**, **30 minutes before**, **1 hour before**, **2 hours before**, **1 day before**, **2 days before**. |
| **repeat** | **does not repeat**, **every day**, **every week**, **every month**, **every year**. |
| **location** | Opens a prompt to type the place. |
| **description** | Opens a prompt to type the description, on one line. |

A new event starts at the next full hour (or at the hour you tapped in a grid), lasts one hour, goes to your default calendar and takes your default reminder.

An event whose rule is richer than the five choices (every Tuesday and Thursday, until a date…) shows **repeats (custom rule)**. The rule is kept as it is unless you pick another choice.

### Phone: calendars

The list of the phone's calendars, with the account each belongs to and the service that syncs it. The help line says: **tap a calendar to show or hide it; the ones shown are inverted**. A calendar you cannot write to is marked **read only**; the one new events go to is marked **default**.

### Phone: settings

See "Settings" below.

### Computer: the window

One window in two parts.

The left column holds:

- a small month, with **‹** and **›** to change month. A dot marks the days that hold something; today is inverted. Click a day: the agenda from that day. Click the month's name: back to today's agenda;
- the views: **agenda**, **day**, **week**, **workdays**, **month**;
- **search**;
- **+ new event**;
- the calendars, each with a dot of its colour. Click one to hide or show it: a hidden calendar has an empty ring and a dimmed name. A calendar you cannot write to says **read only**. The last calendar shown cannot be hidden;
- at the bottom, the status line and **⚙** for the settings.

The right side shows the chosen view.

### Computer: agenda

The days as a list, like on the phone. Click an event for its page, a day heading for that day's time grid, **show more days** for 60 more days. **nothing planned** when the list is empty.

### Computer: day, week and workdays

The time grid of the phone. Above it: **‹**, the dates, **today** and **›**.

- Click a block: the event's page.
- Click an empty slot: a new event at that hour, one hour long.
- Click a day heading (week): that day alone.
- Drag a block: the event moves, by quarter hours and whole days.
- Click an all-day event in the strip above: its page.
- In **workdays**, click the weekend strip at the right: the whole week.

### Computer: month

Six weeks; each day with its events: a dot of the calendar's colour, the hour when there is room, the title. All-day events are solid bars. **+n** when a day is full. Above: **‹**, the month, **today**, **›**.

- Click an event: its page.
- Click a day: its time grid.
- Double-click an empty part of a day: a new event that day at 09:00.
- Drag an event to another day: it moves there.

### Computer: event

**← back**, and at the right **edit** and **delete** (absent when the calendar is read-only). Then the title, the date, the hours, the calendar with its account (followed by **· read-only** when it is), the **repeat**, the **reminder**, the **location** and the description.

A mail address or a web address opens where it belongs. The place opens a map search in the browser. A phone number is copied (the status line says so). All text can be selected and copied.

### Computer: new event and edit

One column. **← cancel** at the top left, **save** at the top right; **cancel** and **save** again at the bottom.

- The **title** is typed in place. Enter saves.
- The date, marked **day**: click for a month grid (**‹** **›**, or the ← → keys).
- The hours, marked **time**: click to type the start, then the end (**start time**, **end time**).
- **all day** switches to an all-day event; **at set times** switches back.
- **ends another day** picks an end date; a row marked **ends** then shows it.
- The calendar, **reminder** and **repeat**: click for the choices. The repeat choices are the same as on the phone; the reminder choices stop at **1 days before**.
- **location** and **description** are typed in place.

When you edit one event of a series alone, the repeat row says **part of a series** and the calendar cannot be changed.

### Computer: search

A field marked **search events: title, place, notes**. Results appear as you type, under **upcoming** and **past**. Each shows the title, the day, the hours, the calendar, **repeats** for a series, and the place. Click one for its page; **← back** returns to the results.

### Computer: settings

See "Settings" below.

## How to

### Add an event (phone)

1. Tap **+ new event** at the bottom of any view, or tap an empty slot in a time grid, or long press a day in the month or a day heading in the agenda.
2. Type the title, then **ok**.
3. Tap the date or the hours to change them.
4. Change the calendar, the reminder, the repetition, the place or the description if needed.
5. Tap **save**. The event's page opens.

### Add an event (computer)

1. Click **+ new event** (or Ctrl+N), or click an empty slot in a time grid, or double-click a day in the month.
2. Type the title.
3. Click the day or the hours to change them.
4. Click **save** (or Ctrl+S, or Enter in the title).

### Change an event

1. Open the event.
2. Choose **edit**.
3. Change what you want, then **save**.

### Change one event of a series, or the series

When you edit, move or delete an event that repeats, the app asks what the change is for.

- On the phone: **only this event**, **this and the following events**, **the whole series**.
- On the computer, for example when editing: **edit only this event**, **edit this and the following events**, **edit the whole series** (and the same with **move** and **delete**).

On the first event of a series, "this and the following" is left out, since it is the whole series. For a series in a Google account on the computer, only "only this event" and "the whole series" are offered.

### Move an event by dragging it

- Phone: long press the event in a time grid or in the month, drag it, release.
- Computer: drag it with the mouse.

In a time grid the event moves by quarter hours and whole days; in the month, by whole days. If it repeats, a menu asks which events to move; close the menu without choosing and the event goes back. An event of a read-only calendar cannot be moved.

### Delete an event

1. Open the event.
2. Choose **delete**.
3. On the phone, confirm with **delete** under **delete this event?**. On the computer, click **delete** in the small menu.

### Make an event repeat

In the form, open **repeat** and choose **every day**, **every week**, **every month** or **every year**. Choose **does not repeat** to stop a series.

### Set a reminder

In the form, open **reminder** and choose. New events take the default reminder of the settings.

### Make an all-day event, or one over several days

- Phone: tap **all day: off** so that it reads **all day: on**. For several days, tap **ends another day** (or the row marked **ends**) and pick the last day.
- Computer: click **all day**. For several days, click **ends another day** and pick the last day.

### Move an event to another calendar

In the form, open the calendar row, choose the other calendar, then **save**. The event is written in the new calendar first, then removed from the old one. One event of a series cannot be moved alone.

### Show or hide a calendar

- Phone: **⋯** › **calendars**, then tap the calendar. Shown calendars are inverted.
- Computer: click the calendar in the left column.

### Choose where new events go

- Phone: **⋯** › **settings** › **new events go to: …**.
- Computer: **⚙** › **default calendar**.

### Go to another date, and come back to today

- Phone: swipe sideways in the week, the day or the month. **⋯** › **today** comes back.
- Computer: **‹** and **›**, or the ← and → keys; **today** comes back. In the small month, click any day.

### Call, write or find the way from an event

Open the event and tap or click the phone number, the address or the place. On the phone, if no app can handle it, the message **no app for this on the phone** appears.

### Find an event (computer)

1. Click **search** (or Ctrl+F).
2. Type one or several words. They are looked for in the title, the place, the description and the calendar's name; capitals and accents do not matter.

The search covers one year back and two years ahead. A series appears once. Escape empties the field, then leaves the search.

### Connect a calendar server (computer)

1. Press Ctrl+, then click the row **CalDAV** under **accounts**.
2. Fill in **server**, **username** and **app password**.
3. Click **connect**.

### Show a Google calendar without an account (computer)

1. In Google Calendar, open the calendar's settings › Integrate calendar, and copy the "Secret address in iCal format".
2. In the accounts dialog, add a line under **feeds**: a name, the sign `|`, then the address.
3. Click **connect**.

The calendar is read-only. Any other `.ics` or `webcal` address works the same way.

### Connect a Google account, read and write (computer)

Google gives no ready-made access to a program like this one: you create your own, once. The dialog sums up the steps:

1. At console.cloud.google.com, create a new project.
2. Under APIs & Services, enable the Google Calendar API.
3. Set up the OAuth consent screen: external, yourself as test user. Then choose "Publish app": left in testing, Google asks you to connect again every 7 days.
4. Under Credentials, create an OAuth client ID of type "Desktop app".
5. Copy its ID into **client ID** and its secret into **client secret**.
6. Click **connect the Google account**. The state reads **waiting for the browser…** and the browser opens on Google. At "Google hasn't verified this app", choose Advanced, then continue: it is your own access.
7. The browser ends on a page saying **Reader's Calendar is connected. You can close this tab.** The dialog reads **Google account connected**.
8. Click **connect**.

The calendars of the account then appear with the others. Those you may only read (shared with you, holidays…) stay read-only.

### Forget the Google account (computer)

Open the accounts dialog and click **forget the Google account**.

### Set up another computer

1. On the first computer: **⚙** › **export credentials…**, and choose where to write the file (it is proposed as `readers-credentials.json`).
2. Carry the file to the other computer.
3. There: **import credentials…** in the first-start dialog or in the settings.
4. Delete the file: it holds your passwords.

### Put a widget on the home screen (phone)

Use your launcher's way of adding a widget and choose **Reader's Calendar · next event** or **Reader's Calendar · today and tomorrow**.

### Change the look quickly

- Phone: **⋯** › **black on white** or **white on black**.
- Computer: Ctrl+T for the colours, Ctrl+= and Ctrl+- for the text size.

## Settings

### On the phone

**⋯** › **settings**. Tap a row to move to its next choice; the first two open a list.

| Setting | Choices | Default |
|---|---|---|
| **new events go to: …** | any calendar you may write to | the first one |
| **default reminder: …** | **no reminder**, **at the time of the event**, **10 minutes before**, **30 minutes before**, **1 hour before**, **2 hours before**, **1 day before** | **10 minutes before** |
| **week starts on: …** | **monday**, **sunday** | **monday** |
| **opens on: …** | **today (list)**, **week**, **workdays**, **day**, **month** | **week** |
| **theme: …** | **white on black**, **black on white**, **follow system** | **white on black** |
| **font: …** | **serif**, **sans**, **mono** | **sans** |
| **text size: …** | **small**, **medium**, **large** | **medium** |
| **alignment: …** | **left**, **center** | **left** |
| **haptic feedback: …** | **on**, **off** | **on** |
| **events: …** | **plain**, **in their calendar's colour** | **plain** |

**haptic feedback** is the short vibration felt when a long press lifts an event.

With **events: in their calendar's colour**, the blocks of the grids and the lines of the month are filled with the colour of their calendar, and the agenda puts a dot of that colour before each title.

The **workdays** view always starts on Monday.

The last two rows give the version (**reader's calendar 1.15.2**, **black and white, text only. MIT licence.**) and the credits.

### On the computer

**⚙** or Ctrl+,. Click a row to move to its next choice.

| Setting | Choices | Default |
|---|---|---|
| **colours** | **black on white**, **white on black** | **black on white** |
| **events** | **plain, with a colour dot**, **in their calendar's colour** | **plain, with a colour dot** |
| **text size** | 9 to 24 pt, with **−** and **+** | **13 pt** |
| the font (the name of the typeface used is shown under the choice) | **sans-serif**, **serif**, **mono** | **sans-serif** |
| **opens on** | **week**, **workdays**, **month**, **day**, **agenda** | **week** |
| **first day of the week** | **monday**, **sunday** | **monday** |
| **default reminder** | **no reminder**, **at the time of the event**, **10 minutes before**, **30 minutes before**, **1 hours before**, **2 hours before**, **1 days before** | **10 minutes before** |
| **default calendar** | any calendar you may write to | the first one |

Under **accounts**:

- **CalDAV**: the server's name, or — when there is none. Opens the accounts dialog.
- **Google**: **Google account connected**, or —. Opens the accounts dialog.
- **feeds**: the number of feeds. Opens the accounts dialog.
- **sync now**: reads the calendars again at once.
- **export credentials…** and **import credentials…**.

## Your data

### On the phone

Your events live in the phone's own calendar storage, where every calendar app of the phone finds them. The app reads and writes there and nowhere else. It never uses the network: your accounts and their sync apps carry the changes to your servers, at their own pace.

A change made elsewhere and synced while the app is open shows at once.

The app keeps only its settings on the phone: the look, the opening view, the default calendar and reminder, and the calendars you hid. Uninstalling removes these settings; your events stay in the phone's calendars and on your accounts.

There is no export or import.

### On the computer

Your events stay on your servers. The program keeps no copy: it reads them at each start, every 5 minutes, after each change you make, and when you press F5 or **sync now**. Without a connection it shows nothing.

What goes over the network, and to whom:

- to your CalDAV server: your login and password, and the events you read and write;
- to the address of each feed: a request for the calendar file;
- to Google, if you connected an account: the connection through your browser, then the events you read and write;
- nothing to anyone else. Clicking a place opens a map search on openstreetmap.org in your browser.

If an event was changed elsewhere while you were editing it, your change is refused rather than written over the other one. For Google the status line says **Google: the event changed elsewhere — shown again as it is now**. Guests of a Google event are not e-mailed about your changes; its guests, colours and meeting links stay as they were.

The settings file holds the server address, the login, the password, the feeds, the Google access and connection, the hidden calendars and the look. It is readable by you only. It is `config.json` in:

- Linux: `~/.config/readers-calendar/`
- Windows: the folder `Readers Calendar` of your application data (`%APPDATA%`)
- macOS: `~/Library/Application Support/readers-calendar/`

Uninstalling the program leaves this file in place; delete it yourself to remove your password from the computer.

### The credentials file

**export credentials…** writes your accounts (server, login, password, feeds, Google access and connection) into a file. Reader's Calendar, Reader's Tasks and Reader's Notes can share the same file, each in its own part: exporting into an existing file adds to it. The look and the other settings are not in it.

The file holds your passwords in clear. Carry it on a USB key or in your own cloud folder, not by e-mail, and delete it once imported.

## With the other apps

### Widgets (phone)

Two home-screen widgets, for any launcher. They follow the app's theme and show today's and tomorrow's events from the calendars you did not hide.

- **Reader's Calendar · next event**: one line with the title and the time; **+** for a new event. Tap the line to open the event. A timed event takes the line from one hour before its start until its end; an all-day event shows the rest of the time. **nothing planned** when nothing is left today or tomorrow.
- **Reader's Calendar · today and tomorrow**: a list, under the word **agenda** (tap it to open the app) and a **+** for a new event. Tap an event to open it.

### Opened by other apps (phone)

The app answers the phone's calendar links: another app can open it on a day, on an event, or on a new event. This is how the agenda tile of Reader's Launcher opens it, and why it can be chosen as the phone's calendar app.

### The computer and the phone together

The two programs do not talk to each other. They show the same events when the phone syncs the same accounts as the computer.

## On the computer

### How it differs from the phone

- It connects to your servers itself; the phone app relies on the phone's accounts.
- It has a search.
- The month view opens an event with one click; on the phone a tap opens the day.
- A phone number is copied instead of dialled.
- There are no widgets.
- The description is a multi-line field.

### Keyboard

| Key | Effect |
|---|---|
| ← / → | previous / next week or day in the grids, month in the month view and in the small month |
| Ctrl+N | new event |
| Ctrl+S, Ctrl+Enter | save the event being edited |
| Ctrl+F | search |
| Ctrl+D | today's agenda |
| Ctrl+J | today as a time grid |
| Ctrl+W | this week |
| Ctrl+Shift+W | workdays |
| Ctrl+M | this month |
| Escape | back (empties the search field first) |
| F5, Ctrl+R | sync now |
| Ctrl+T | white on black / black on white |
| Ctrl+= , Ctrl++ / Ctrl+- | larger / smaller text |
| Ctrl+, | settings |
| Ctrl+Q | quit |

### Command line

- `readers-calendar --export-credentials FILE` writes the accounts into FILE, without opening the window.
- `readers-calendar --import-credentials FILE` reads them back.

### Installing

- Debian, Ubuntu, Pop!_OS: the `readers-calendar` package.
- Windows: one `.exe` file, nothing to install. It is not signed: at "Windows protected your PC", choose More info › Run anyway.
- macOS: a `.dmg`. The first opening must be a right click on the app › Open.

## Limits

Both programs:

- no invitations, no guests;
- no time zone other than the device's: hours are shown and entered in local time;
- no alert: the reminder is stored with the event for the devices that do alert;
- one reminder per event;
- the repetition choices are every day, week, month or year; a richer rule made elsewhere is kept but cannot be built here.

Phone:

- no search;
- the description is typed on one line;
- the widgets look no further than tomorrow;
- all-day events cannot be dragged in the time grids (they can in the month).

Computer:

- one CalDAV account and one Google account;
- feeds are read-only;
- nothing is shown without a connection;
- a Google series offers "only this event" or "the whole series", not "this and the following";
- the search shows at most 150 results under each heading.

## Messages and problems

### On the phone

| Message | Meaning, and what to do |
|---|---|
| **allow access to the calendars** | The calendar permission was refused. Tap the row to grant it. |
| **nothing planned** | No event in the days shown, in the calendars shown. Check **calendars** if you expected some. |
| **the end is before the start** | The end must be after the start. Correct the hours or the end date. |
| **not saved** or **not saved: …** | The phone refused to write the event; the words after the colon are the system's own. |
| **this calendar is read only: its events cannot be changed here** | You may only read the calendar this event belongs to. The event cannot be edited, deleted or moved from the app. |
| **no app for this on the phone** | No app can open this number, address or place. |
| **(hh:mm)** added to a time prompt | What you typed is not a time. Type hours and minutes. |
| **(untitled)** | The event has no title. |
| **repeats (custom rule)** | The event repeats by a rule richer than the app's choices. |

A calendar is missing: the app lists the calendars the phone holds and shows. Check the account or the sync app that brings it.

A change does not reach your other devices: the app wrote it on the phone; sending it is the work of the account's sync.

### On the computer

Messages appear in the status line, at the bottom of the left column.

| Message | Meaning, and what to do |
|---|---|
| **not connected — Ctrl+, to set up** | No account yet. Press Ctrl+, and open a row under **accounts**. |
| **wrong username or app password** | The server refused the login. Check both; use an application password if two-factor authentication is on. |
| **no calendar found at this address** | The server answered but holds no calendar there. Check the address. |
| **this server address is not valid** | The address is malformed, or lacks `https://` at its start. |
| **cannot reach the server** | No connection, or a wrong server name. |
| **the server did not answer in time** | The server is slow or unreachable. Try F5 later. |
| **the server refused the request (HTTP …)** | The server rejected a read or a change. With 412, the event changed elsewhere: press F5 and redo your change. |
| **the server sent an unreadable answer** | The address is probably not a CalDAV server. |
| **network error — …** | Another network failure; the details follow. |
| **feed: HTTP …** | A feed's address answered with an error. Check the address in **feeds**. |
| **this event comes from a read-only feed** | Feeds cannot be changed. |
| **this calendar is read-only** | You may only read this Google calendar. |
| **no writable calendar** | No calendar you may write to: a new event has nowhere to go. |
| **the end is before the start** | Correct the hours or the end date. |
| **title** | You saved without a title. Type one. |
| **Google: connect the account again (Ctrl+,) to edit its events**, **connected read-only — forget, then connect again to edit** | The Google connection only allows reading. Click **forget the Google account**, then connect again. |
| **Google: HTTP … — connect the account again** | Google no longer accepts the connection. Forget the account and connect again. |
| **Google: the event changed elsewhere — shown again as it is now** | Your change was not written. Redo it on the event as it now is. |
| **Google answered with an error (HTTP …): …** | Google rejected a request; its own words follow. |
| **Google: the browser did not come back** | The consent in the browser was not finished within five minutes. Try again. |
| **Google: access was refused in the browser** | You declined on Google's page. |
| **Google: the answer in the browser did not match this request — try again** | An old browser tab answered. Try again. |
| **Google: Google sent no authorisation code**, **Google refused access: …**, **Google refused the connection (HTTP …): …** | The connection failed at Google. Check the client ID and secret, then try again. |
| **Google: Google did not grant lasting access — remove this app from your Google account's connections, then connect again** | Do as it says, in your Google account's security settings. |
| **Something went wrong. Close this tab and try again.** | Shown in the browser when the Google connection failed. |
| **credentials exported to … — the file holds your passwords: keep it private** | The export worked. |
| **credentials imported** | The import worked; the program connects. |
| **not a Reader's credentials file** | The chosen file is not a credentials file. |
| **this file holds nothing for readers-calendar** | The file has no part for this program. |
| **cannot use this file — …** | The file could not be read or written. |
| **… copied** | The phone number you clicked is in the clipboard. |
| **searching further…** | The search is still reading the wider period. |
| **no event found** | Nothing matches the words typed. |
| **error — …** | Any other failure; the details follow. |


# Reader's Tasks

*Android 1.5.2 · Windows, macOS, Linux 1.6.2*

## What it is

Reader's Tasks shows the task lists you keep on a CalDAV server (Infomaniak, Nextcloud, Tasks.org Cloud, Radicale…) as plain text in black and white: a box to tick, a line to add a task, and very little else. It exists as an Android app and as a program for Windows, macOS and Linux; both talk to the same server, so a task ticked, renamed or moved in one shows the same in the other. There is no account with the app itself: only your own server, its address, your username and your password.

It deliberately has no priorities, no projects, no reminders, no notifications and no notes attached to a task. It does not create, rename or delete the lists themselves: that is done on your server or in another app.

Both programs speak English, French, German, Spanish, Portuguese and Russian, and follow the language of the system.

This chapter describes the Android app first. The desktop program has its own section, "On the computer".

## First start

The Android app asks for no permission. It only uses the network, to reach your server.

At the first opening the screen shows the title **Reader's Tasks ▾** and one line: **set up your account**. Tap it to open the **account** screen. The screen starts with this help text: "Any CalDAV server with task lists: Infomaniak (https://sync.infomaniak.com, username like AB12345), Tasks.org Cloud, Nextcloud… Use an application password when two-factor authentication is on."

| Field | What to put in it | Example shown by the app |
|---|---|---|
| **server** | the full address of your CalDAV server, starting with `https://` | `https://sync.infomaniak.com` |
| **username** | your username on that server | `AB12345` |
| **app password** | your password; an application password created on the server when two-factor authentication is on | |

Then tap **connect**. The line **connecting…** appears. When the app has found your task lists, the screen closes by itself and the first list is displayed. If something is wrong, a message stays under **connect** (see "Messages and problems").

If you already use Reader's Tasks on another phone or on a computer, you can tap **import credentials** on the same screen instead of typing (see "Set up another phone or a computer").

A list with nothing to do shows **no open task**.

## The screens

### The tasks (main screen)

The main screen shows the open tasks of one list, the current list.

- **The title**, at the top, is the name of the current list followed by **▾**. Tap it to open the **lists** screen.
- **⋯**, at the top right, opens the menu of the screen (below).
- **Each task** is a line with a box **☐** and its text, on two lines at most. A task with a due date shows it in small letters underneath: **today**, **tomorrow**, **3 d late** (the number of days), the name of the weekday when it is less than a week away, otherwise the day and the month.
  - Tap **☐**: the task is completed.
  - Tap the text: a prompt titled **task** opens to rename it.
  - Long press without moving: the menu of the task opens (below).
  - Long press, then drag: the task moves up or down in the list.
- **show 4 done** (with the number of completed tasks) appears under the open tasks when the list has completed tasks. Tap it to display them, dimmed, with a ticked box **☑**, the most recently completed first; the line becomes **hide 4 done**. Tap the **☑** or the text of a completed task to reopen it; long press it for its menu. The completed tasks are folded away again when you leave the screen.
- **+ new task**, at the bottom, opens the prompt **new task**.
- **The last line**, in small letters, says **syncing…** while the app talks to the server, then **synced 14:32** (the time of the last sync), or the error if the sync failed.

The menu **⋯** has four entries:

| Entry | What it does |
|---|---|
| **lists** | opens the **lists** screen |
| **sync now** | reloads all lists and all tasks from the server |
| **black on white** or **white on black** | switches to the other look; the entry names the look you will get |
| **settings** | opens the **settings** screen |

### The menu of a task

A long press on a task opens a menu with the text of the task as its title:

| Entry | What it does |
|---|---|
| **complete** (open task) or **reopen** (completed task) | ticks or unticks the task |
| **call …**, **write to …**, **open …** | one entry for each phone number, e-mail address or web address written in the task (see "Call a number, write to an address or open a page written in a task") |
| **rename** | opens the prompt **task** with the current text |
| **due tomorrow** | sets the due date to tomorrow, replacing any other due date |
| **no due date** | removes the due date |
| **delete** | deletes the task from the server, at once and without asking |

Tap outside the menu, or press back, to close it without doing anything.

### The prompts **new task** and **task**

Both are one line of text with two buttons: **cancel** and **add** (new task) or **ok** (rename). The confirm key of the keyboard does the same as **add** or **ok**. An empty line cannot be confirmed. Tap outside the prompt, or press back, to cancel.

### lists

The **lists** screen shows the task lists of your server, each with its number of open tasks underneath. The current list is shown inverted.

- Tap **← lists** at the top, or press back, to return.
- Tap a list: it becomes the current list and the main screen comes back.
- Long press a list: a menu with **move up**, **move down** and **hide this list**. **move up** is missing on the first list, **move down** on the last one, and **hide this list** when only one list is left on screen.
- **2 hidden** (with the number of hidden lists) appears at the bottom when lists are hidden. Tap it to display them, each with **show again** underneath; tap one to bring it back among the others. **hide the hidden lists** folds them away.

### settings

Reached by **⋯** then **settings**. Tap **← settings** or press back to return. The screen holds, from top to bottom:

- **account**, with your username underneath (or **set up your account**): opens the **account** screen.
- **export credentials** and **import credentials** (see "Your data").
- the five settings of the look, described under "Settings". Each tap on a line moves to its next choice.
- **reader's tasks 1.5.2**, with **black and white, text only. MIT licence.** underneath, and **Pierre Gallaz · developed with Claude Code**. These two lines only inform.

### account

The three fields **server**, **username** and **app password**, the button **connect**, then **export credentials** and **import credentials**. See "First start".

## How to

### Add a task

1. Open the list the task belongs to.
2. Tap **+ new task** at the bottom.
3. Type the task and tap **add**.

The task is sent to the server and appears in the list. It has no due date.

### Complete a task

Tap its **☐**. The task leaves the list at once and is marked completed on the server. You can also long press it and choose **complete**.

### Reopen a task ticked by mistake

1. Tap **show … done** under the open tasks.
2. Tap the **☑** of the task, or its text.

### Rename a task

1. Tap the text of the task (or long press it and choose **rename**).
2. Change the text and tap **ok**.

The due date is kept. For a completed task, use the long press and **rename**: a tap on its text reopens it.

### Give a task a due date, or remove it

1. Long press the task.
2. Choose **due tomorrow** to set the due date to tomorrow, or **no due date** to remove it.

Tomorrow is the only date the app can set. Due dates set elsewhere (the server's web page, another app) are displayed under the task.

### Delete a task

Long press the task and choose **delete**. There is no confirmation and no way back.

### Put the tasks in your own order

1. Long press a task until it lifts (its line turns slightly grey).
2. Without lifting the finger, drag it up or down to its place; the list scrolls when you reach its top or bottom edge.
3. Let go.

The order is saved on the server, so the desktop program and other apps that follow the same convention show the same order. Tasks you have never moved come after the ones you placed, sorted by due date (tasks without a date last), then by creation date. Completed tasks cannot be dragged.

### Call a number, write to an address or open a page written in a task

A tap on a task never opens anything. When the text of a task holds a phone number (7 to 15 digits), an e-mail address or a web address (starting with `http://`, `https://` or `www.`), the menu of the task offers it:

1. Long press the task.
2. Choose **call** followed by the number, **write to** followed by the address, or **open** followed by the web address.

**call** opens the phone's dialler with the number filled in; the call does not start by itself. **write to** opens your mail app, **open** your browser. The menu offers up to eight of them per task.

### Switch to another list

Tap the name of the list at the top (or **⋯** then **lists**), then tap the list you want.

### Hide a list, or bring it back

1. Open **lists**.
2. Long press the list and choose **hide this list**.

To bring it back: on **lists**, tap **… hidden** at the bottom, then tap the list marked **show again**. Hiding only concerns this phone; nothing changes on the server.

### Change the order of the lists

On **lists**, long press a list and choose **move up** or **move down**, as many times as needed. The order is kept on this phone only.

### Sync now

Tap **⋯** then **sync now**. The app also syncs by itself: when it comes to the screen and the last sync is more than two minutes old, and after each of your actions (for the list concerned).

### Switch between white on black and black on white

Tap **⋯** then **black on white** (or **white on black**). This is the same setting as **theme** in **settings**.

### Change the account or the password

1. Tap **⋯**, **settings**, **account**.
2. Correct the fields and tap **connect**.

### Set up another phone or a computer

On the phone that already works:

1. Tap **⋯**, **settings**, **export credentials**. Underneath, the app reminds you: "a file to set up another phone or the desktop app — it holds the password: keep it private".
2. Android's share sheet opens with a file named `readers-credentials-tasks.json`. Send it to yourself by a private way (your own cloud folder, a message to yourself).

On the new phone:

1. Put the file where the phone can reach it (downloaded, or in a cloud folder).
2. In Reader's Tasks, tap **set up your account** (or **settings**), then **import credentials**, and choose the file.
3. The message **credentials imported** appears and the app connects.

On a computer, see "Move the account to another computer" under "On the computer". Delete the file once it has been imported: it holds your password, readable by anyone who opens it.

## Settings

All in **settings**. Each tap on a line moves to the next choice.

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **theme** | the colours of the app and of its widgets | **white on black**, **black on white**, **follow system** | **white on black** |
| **font** | the typeface of all text | **serif**, **sans**, **mono** | **sans** |
| **text size** | the size of all text | **small**, **medium**, **large** | **medium** |
| **alignment** | text aligned on the left or centred | **left**, **center** | **left** |
| **haptic feedback** | a short vibration when you tick a box or long press | **on**, **off** | **on** |

**follow system** takes the dark or light mode of Android.

## Your data

### Where it lives

Your tasks live on your CalDAV server. The phone keeps a copy of the lists and tasks from the last sync, so the app opens at once and shows them even without a network. The server address, the username and the password are kept in the app's private storage on the phone, as are the look, the order of the lists, the hidden lists and the current list.

### What goes over the network

The app talks to one machine only: the server whose address you entered, with your username and password, over an encrypted connection (`https://`). Nothing is sent to anyone else: no statistics, no tracking. An address starting with `http://` is refused by the app, except for a server running on the device itself.

### Sync and conflicts

- The app reloads everything from the server when it opens with data older than ten minutes, when it returns to the screen with data older than two minutes, and when you choose **sync now**. After each action it reloads the list concerned.
- Every action (add, complete, reopen, rename, due date, delete, reorder) is sent to the server straight away. Nothing is queued for later: with no network the action fails and the last line shows the error. A task you ticked or deleted while offline disappears from the screen, then comes back at the next successful sync, because the server never received the change.
- When a task was changed elsewhere since your last sync, the server can refuse your change rather than overwrite the other one. The last line then shows **sync failed:** followed by the refusal. Choose **sync now**, then do it again.
- A list created on the server appears after the next sync, at the end of your lists. A list deleted on the server disappears from the phone.

### The credentials file

**export credentials** writes a small file, `readers-credentials-tasks.json`, with the server address, the username and the password, and hands it to Android's share sheet. **import credentials** reads such a file and replaces the account in the app, then connects. The file format is shared by the Reader's apps on phone and computer: each app reads only its own part. The file holds the password in clear. The temporary copy made by the app for sharing is erased at the next export and each time the app starts.

There is no other export: the tasks themselves are on your server.

### Uninstalling

Uninstalling removes the copy of the tasks, the account and the settings from the phone. Nothing is deleted on the server.

## With the other apps

### Home-screen widgets

The app offers two widgets, to add from the widget list of any launcher. Both show the current list of the app (the first visible list if there is none), in the colours of the app's **theme**.

| Widget | Size | What it shows |
|---|---|---|
| **Reader's Tasks · first task** | 4 × 1, can be widened | the first open task of the current list; under it the name of the list and, when there are several tasks, **1/5** (first of five) |
| **Reader's Tasks · open tasks** | 4 × 2, can be widened and made taller | the name of the list, then the open tasks as a scrolling list, each with its due date underneath |

In both widgets:

- **☐** completes the task on the server, without opening the app;
- **+** opens the app directly on the prompt **new task**;
- a tap on the text of a task, or on the name of the list, opens the app.

With no account, the widgets show **set up your account**; with nothing to do, **no open task**. The widgets display what the app loaded last; they are redrawn after each change in the app.

### Reader's Launcher

Reader's Tasks is the app behind the tasks tile of Reader's Launcher. The launcher reads the visible lists and their open tasks from Reader's Tasks, and can add a task or tick one through it. No permission is asked: the two apps recognise each other because they are signed by the same author. Reading the tasks from the launcher also starts a sync when the data is more than ten minutes old.

### Other apps on the same server

Any other app connected to the same CalDAV account sees the same tasks. The order given by dragging is stored in a way that Apple Reminders, Nextcloud Tasks and Tasks.org also use.

The app does not appear in Android's share menu and does not open files, apart from the credentials file.

## On the computer

The desktop program does the same job in one window. It is obtained as described in the chapter on getting the apps: `readers-tasks` from the apt repository or a `.deb` on Debian, Ubuntu and Pop!_OS, a PKGBUILD for Arch, a single `.exe` for Windows, a `.dmg` for macOS.

### First start on the computer

At the first start a dialog titled **reader's tasks** opens. It says: "CalDAV task lists. For Tasks.org Cloud: in the Android app, ⚙ › App settings › Tasks.org › Generate new password, and copy the URL, username and app password shown there."

1. Fill in **server** (the example shown is `https://caldav.tasks.org/…`), **username** and **app password**.
2. Click **connect**.

The dialog closes, the status line at the bottom of the window shows **connecting…**, then your lists appear. A wrong address or password is reported in that status line; press Ctrl+, to open the dialog again. If you click **cancel** at the first start, the status line says **not connected — Ctrl+, to set up**.

The dialog also has **import credentials…** and **export credentials…**, and shows the version at the bottom (**reader's tasks 1.6.2 · Pierre Gallaz · developed with Claude Code**).

### The window

- **On the left**, the column of your lists. Click a list to display it; the current list is shown inverted. Right click for the menu of the lists.
- **On the right**, the open tasks of the current list, each with **☐**, its text and, in small letters, its due date (same wording as on the phone). An empty list shows **no open task**.
- **show 4 done** / **hide 4 done**, under the tasks, displays or hides the completed tasks, dimmed, with **☑**.
- **The line + new task**: type a task and press Enter.
- **The status line**, at the very bottom: **3 open · synced 14:32**, or what the program is doing (**syncing…**, **adding…**, **renaming…**, **saving order…**), or an error.
- **⚙**, at the bottom right (tooltip **server settings (Ctrl+,)**), opens the setup dialog.

### What the mouse does

| Gesture | Effect |
|---|---|
| click **☐** | completes the task |
| click **☑** | reopens the completed task |
| double click on the text of a task | renames it: a dialog **rename** with the field **task** and the buttons **rename** and **cancel** |
| drag an open task up or down | puts it at its place; the order is saved on the server (**saving order…**) |
| right click on a task | **complete** (or **reopen**), **rename**, **delete** |
| right click on a list | **move up**, **move down**, **hide this list**, **show a hidden list** |

**delete** removes the task from the server at once, without asking. **show a hidden list** opens a second menu with the names of the hidden lists; click one to bring it back. The program refuses, without a message, to hide the last list left. The order of the lists and the hidden lists are kept on this computer only; they are independent from the phone's.

### Keyboard shortcuts

| Key | Effect |
|---|---|
| Enter in the line **+ new task** | adds the task to the current list |
| Ctrl+N | puts the cursor in the line **+ new task** |
| Ctrl+D | shows or hides the completed tasks |
| F5 or Ctrl+R | syncs now |
| Ctrl+T | switches between black on white and white on black |
| Ctrl+= or Ctrl++ | larger text |
| Ctrl+- | smaller text |
| Ctrl+, | opens the setup dialog (server, username, app password) |
| Ctrl+Q | quits |

### How it differs from the phone

- The lists are always visible on the left; there is no separate lists screen.
- It starts black on white. There is no settings screen: the look is changed by Ctrl+T and by Ctrl+= / Ctrl+- (text size from 9 to 30 points, 15 at the start). There is no choice of font or alignment, and no **follow system**.
- It cannot set or remove a due date; it displays the ones that exist. Its task menu has no **call**, **write to** or **open** entries.
- Subtasks made in another app are displayed as ordinary tasks; the phone app hides open subtasks.
- It syncs the current list every 5 minutes, at each change of list, after each action, and on F5 or Ctrl+R. The lists themselves are read when the program connects: a list created on the server appears at the next start, or after Ctrl+, and **connect**.
- It keeps no copy of the tasks: without a network the window stays empty and the status line shows the error.
- It has no widgets.

### Move the account to another computer

1. On the computer that works, press Ctrl+, and click **export credentials…**. Choose where to write the file; the name proposed is `readers-credentials.json` in your home folder. The dialog confirms: **credentials exported to … — the file holds your passwords: keep it private**.
2. Carry the file to the other computer by a private way (a USB key, your own cloud folder).
3. There, start Reader's Tasks and click **import credentials…** in the dialog, then choose the file. The dialog closes and the program connects.
4. Delete the file.

The export writes the account already saved in the program, not what you have just typed in the fields: connect first, export afterwards. If you choose an existing credentials file, the program adds its own part to it and keeps the parts of the other Reader's apps (Calendar, Notes): one file can carry all your accounts. The look (colours, text size) is not in the file. A file exported by the phone app can be imported on the computer, and the other way round.

### Command line

The same export and import work without opening the window:

```
readers-tasks --export-credentials FILE
readers-tasks --import-credentials FILE
```

Each prints its result (**credentials exported to …** or **credentials imported**) and stops.

The program's source also comes with a separate script, `copy_tasks.py`, which copies the tasks of one list into another list, on the same server or on another one, for instance when you change provider:

```
python3 copy_tasks.py --from URL USER PASSWORD "LIST" --to URL USER PASSWORD "LIST"
```

Add `--include-completed` to copy completed and cancelled tasks too, and `--dry-run` to see what would be copied without copying. The name of a list is matched without regard to capitals. Nothing is deleted on the source, and a second run skips the tasks already present on the target. The script speaks English only; it ends with a count such as `12 copied, 3 already there, 15 read from the source`, and names the available lists when it cannot find the one you asked for.

### Where its settings live

One file, `config.json`, readable by your user account only:

| System | Folder |
|---|---|
| Linux | `~/.config/readers-tasks/` |
| Windows | `%APPDATA%\Readers Tasks\` |
| macOS | `~/Library/Application Support/readers-tasks/` |

It holds the server address, the username, the password (in clear), the theme, the text size, the order of the lists, the hidden lists and the last list displayed. Deleting this file brings the program back to its first start.

## Limits

- One account, one server at a time.
- The app does not create, rename or delete lists.
- A task is one line of text. Descriptions, priorities, tags, reminders, repetition and attachments set in other apps are neither displayed nor editable; they are left untouched on the server when you tick, rename or move the task.
- No notifications and no reminders, even for a due date.
- On the phone the only due date you can set is tomorrow; on the computer none. The time of day of a due date is not displayed.
- On the phone, open subtasks are not displayed. Cancelled tasks are displayed in neither program.
- No search.
- No work is kept for later when the network is missing: an action made offline is lost.
- On the phone the server address must start with `https://`.
- The widgets display the first open task or the open tasks of the current list only; they cannot show another list than the app.

## Messages and problems

### On the phone

| Message | What it means, what to do |
|---|---|
| **set up your account** | No server is entered yet. Tap the line and fill in the **account** screen. |
| **connecting…**, **syncing…** | The app is talking to the server. Wait. |
| **synced 14:32** | Time of the last successful sync. |
| **no open task** | The current list has nothing left to do. |
| **wrong username or app password** | The server refused the login. Check the username; if two-factor authentication is on, create an application password on the server and use that one. |
| **no task list found at this address** | The server answered, but no list able to hold tasks was found there. Check the address in **server**, and that the account has at least one task list. |
| **this phone cannot send … to the server** | The phone's system cannot send one kind of request that CalDAV needs (its name is shown). The app cannot sync on this phone. |
| **sync failed: …** | Any other failure. The words after the colon come from the system or the server, often in English: no network, an address that does not exist, an address without `https://`, or a refusal by the server such as `PUT: HTTP 412` (the task was changed elsewhere: **sync now**, then try again). |
| **no app for this on the phone** | You chose **call**, **write to** or **open**, and the phone has no app able to do it. |
| **credentials imported** | The account was read from the file; the app connects. |
| **not a Reader's credentials file** | The file chosen was not made by **export credentials** of a Reader's app. |
| **this file holds nothing for Reader's Tasks** | It is a credentials file, but exported by another Reader's app only. Export from Reader's Tasks. |
| **the file cannot be read: …** | The phone could not open the file; the reason follows. |
| **no account to export yet** | Nothing has been entered in **account**. |
| **export failed: …** | The file could not be prepared for sharing; the reason follows. |

A task you ticked comes back by itself: the change did not reach the server. Look at the last line of the screen for the error, then tick again once **sync now** has worked.

A widget shows old tasks: open the app, which syncs and redraws the widgets.

### On the computer

| Message | What it means, what to do |
|---|---|
| **not connected — Ctrl+, to set up** | No server is entered. Press Ctrl+, or click **⚙**. |
| **connecting…**, **syncing…**, **adding…**, **renaming…**, **saving order…** | The program is talking to the server. |
| **3 open · synced 14:32** | Number of open tasks in the list and time of the last sync. |
| **no open task** | The current list has nothing left to do. |
| **wrong username or app password** | The server refused the login. Press Ctrl+, and correct them. |
| **no task list found at this address** | No list able to hold tasks at the address in **server**. |
| **the server refused the request (HTTP …)** | The server answered with an error; the number is its code. After ticking, renaming or moving a task, it usually means the task was changed elsewhere: press F5 and do it again. |
| **the server did not answer in time** | No answer after 30 seconds. Try again later. |
| **cannot reach the server** | No network, or the address leads nowhere. |
| **this server address is not valid** | The address in **server** is incomplete; it must start with `https://`. |
| **network error — …**, **error — …** | Another failure; the detail follows, often in English. |
| **the server sent an unreadable answer** | The address answers, but not as a CalDAV server does. Check the address. |
| **credentials exported to … — the file holds your passwords: keep it private** | The export worked; the file's place is shown. |
| **credentials imported** | The account was read from the file. |
| **not a Reader's credentials file** | The file chosen for import, or the existing file chosen for export, is not a Reader's credentials file. |
| **this file holds nothing for readers-tasks** | It is a credentials file, but without an account for Reader's Tasks. |
| **cannot use this file — …** | The file could not be read or written; the system's reason follows. |


# Reader's Notes

*Android 1.7.0 · Windows, macOS, Linux 1.3.3*

## What it is

Reader's Notes keeps plain-text notes: one list, one page, black and white. A note is a text file whose first line is its title. On the phone you can type a note or dictate it; the speech is turned into text on the phone itself and nothing you say is sent anywhere. If you wish, the notes are kept in step with a folder on your own WebDAV server (kDrive, Nextcloud…), one `.txt` file per note, so that the phone, the desktop app and any other device see the same plain files.

The app deliberately has no formatting (no bold, no lists, no images), no colours, no reminders, no account with anyone but your own server, and no tracking. Without a server the notes simply stay on the device.

Two programs share this chapter: the Android app, and the desktop app for Windows, macOS and Linux, described in "On the computer". Both exist in English, French, German, Spanish, Portuguese and Russian, and follow the language of the system.

## First start

### On the phone

The app asks nothing when it opens. You see the title **notes**, an empty list with the line **nothing yet. The first line of a note is its title.**, and at the bottom two rows side by side, **+ new note** and **● dictate**. Under them a small line reads **on this phone only — tap to set up a WebDAV folder**.

You can write straight away. Two things are asked only when you need them:

- **The microphone**, the first time you tap **● dictate**. It is needed to record what you say. On recent versions of Android the app asks at the same moment for permission to show notifications: while you dictate, a notification shows the running time and a **stop** button.
- **A WebDAV folder**, only if you want the notes on several devices. Tap the small line under the list (or **⋯** then **settings**) and fill the four lines at the top:

| Line | What to put |
|---|---|
| **server** | The address of your server, starting with `https://`. For kDrive: `https://ID.connect.kdrive.infomaniak.com`, where ID is the number in the kDrive web address. Nextcloud and other servers take their usual WebDAV address. |
| **username** | Your login on that server (for kDrive, your Infomaniak login). |
| **password** | Your password; an application password if two-factor authentication is on. |
| **folder on the server** | The folder that holds the notes. It reads **Notes** from the start and is created on the server if it is missing. |

The first time you dictate, the speech model is downloaded (574 MB with the standard choice, see "Settings").

### On the computer

The first time the desktop app opens without a server, the settings window opens by itself with the same four fields. Fill them and press **save**, or press **cancel** to keep the notes on this computer only. The status line under the list then reads **on this computer only — Ctrl+, to set up a WebDAV folder**.

## The screens

### The list of notes (phone)

The title line reads **notes**, with **⋯** on the right. Each note takes two lines: its title (the first line of the note, or **untitled**), then a small line with when it last changed (the time for today, **yesterday**, otherwise the date), the next line of the note, and the sign **✎** when the note has not yet reached the server. While a dictation is being written into a note, that small line shows **fetching the model · N%** or **transcribing · N%** instead.

- **Tap a note** to open it.
- **Long press a note** to open its menu, titled with the note's title: one line for each phone number, mail address or web address found in the note (**call …**, **write to …**, **open …**), then **share**, **move to a folder** (only when folders are on) and **delete**.
- **+ new note** opens an empty note with the keyboard up.
- **● dictate** creates a note and opens it with the microphone on.
- **The small line at the bottom** shows the state of the sync (**syncing…**, **synced 21:03 2↑ 1↓ 1−**, or the error). Tap it to sync now. Without a server it reads **on this phone only — tap to set up a WebDAV folder** and a tap opens the settings. The figures count the notes sent (↑), received (↓) and deleted (−).

The **⋯** menu holds **+ new note**, **find**, **sync now** (only when a server is set), then under a line **black on white** or **white on black** (whichever the app is not showing at present) and **settings**.

When a search is active, the title line shows the searched words in quotation marks with **←** before them; tap it to return to the full list. If nothing matches, the list reads **nothing found**.

### The folders (phone, when folders are on)

With the **folders** setting on, the first page lists the folders instead of the notes: **all notes** first (filled folder sign, with the total number of notes), then each folder in alphabetical order with its number of notes, then **new folder** (dashed sign).

- **Tap all notes** to see every note; notes that sit in a folder show its name on their small line.
- **Tap a folder** to see its notes. The title line shows the folder's name with **←** to go back.
- **Long press a folder** for **rename** and **delete the folder**.
- **Tap new folder**, type the **name of the new folder** and confirm with **ok**.

The bottom rows **+ new note** and **● dictate** and the sync line are the same as in the list. A note started from the folders page or from **all notes** has no folder; a note started inside a folder is filed there. The **⋯** menu also holds **new folder**.

### The note (phone)

The title line shows the first line of the note (or **new note** while it is empty), with **←** to go back and **⋯** on the right. The rest of the page is the text. An empty page reads **write here. The first line is the title.** A tap places the cursor; a long press selects text to copy, cut or paste, as in any text field.

Everything is saved as you type; there is no save button. When you leave the note it is sent to the server if one is set. A note left empty is discarded.

At the bottom, **● dictate** speaks into this note. While the microphone is open the row turns to **■** followed by the running time, under a line that moves with your voice; tap it to stop.

The **⋯** menu holds the **call …**, **write to …** and **open …** lines for what the note contains, then **share** and **delete**, and under a line **black on white** or **white on black**.

### Settings (phone)

One page, reached from **⋯** then **settings**. Tap **←** to go back. Every line is described under "Settings".

### The main window (computer)

On the left: the **find** field, the list of notes (same two lines per note as on the phone), **+ new note**, then the status line and **⚙** for the settings. On the right: the title of the open note with **⋯**, and the page. See "On the computer".

## How to

### Write a note

1. Tap **+ new note**.
2. Type. The first line becomes the title.
3. Tap **←** when you have finished. The note is already saved.

### Dictate a new note

1. On the list, tap **● dictate**. Allow the microphone the first time.
2. Speak. The page reads **speak. Tap ■ when you have finished; the words appear a moment later.** The microphone stays open with the screen off; a notification, **dictating**, shows the time and a **stop** button.
3. Tap **■** (or **stop** in the notification).
4. Wait a moment: the row shows **transcribing · N%** (and **fetching the model · N%** the first time), then the text appears in the note, cut into paragraphs at your pauses.

You may leave the note or the app while the words are being written; the notification then reads **writing what was said**, and the text is added to the note when ready. The sound is deleted once its text is in the note. A recording shorter than about half a second is ignored.

### Dictate into an existing note

1. Open the note and tap where the words should go.
2. Tap **● dictate**, speak, tap **■**.

The words arrive at the cursor, with a space before or after when needed. If you have left the note meanwhile, they are added at its end, after an empty line. You can start another dictation while the previous one is still being written.

### Find a note

1. Tap **⋯**, then **find**.
2. Type a word or a few letters and tap **find**.

The list keeps only the notes whose text contains what you typed, capitals ignored. Tap the title line (**←**) to return to the full list. From the folders page the search covers all notes; from inside a folder it covers that folder only.

### Call a number, write to an address, open a link found in a note

1. Long press the note in the list, or open it and tap **⋯**.
2. Tap **call …**, **write to …** or **open …**.

The phone app opens with the number ready; it never calls by itself. A mail address opens your mail app, a web address your browser. Up to eight such lines are offered per note. Phone numbers need 7 to 15 digits, so dates, prices and room numbers are left alone; web addresses must begin with `http://`, `https://` or `www.`.

### Share a note

Long press the note (or open it and tap **⋯**), then **share**. The whole text is handed to the app you pick, with the title as subject.

### Delete a note

Long press the note (or open it and tap **⋯**), then **delete**. There is no confirmation and no bin. If a server is set, the file is deleted there too at the next sync.

### Turn text from another app into a note

In the other app, select or share text and choose Reader's Notes in the share menu. A new note opens with that text. If the other app gave a subject, it becomes the first line.

### Keep the notes in step with a server

1. Open **settings** and fill **server**, **username**, **password** and, if needed, **folder on the server**.
2. Tap **sync now** on the same page.

From then on the sync runs by itself: when the app opens (unless **sync when the app opens** is off), when you leave a note, when you leave the app with something not yet sent, after a deletion or a move, and whenever you tap **sync now** or the status line.

### Stop the sync on the phone

1. Open **settings** and tap the **server** line.
2. Erase the address and tap **ok**.

The line under the list reads **on this phone only — tap to set up a WebDAV folder** again. Every note stays on the phone, and the files on the server are left as they are.

### File notes in folders

1. In **settings**, tap **folders** to turn it **on**.
2. Back on the first page, tap **new folder**, name it, confirm.
3. To file an existing note: open **all notes**, long press the note, tap **move to a folder**, then the folder. The current place is marked **●**; **no folder** takes the note out of its folder.

### Rename or delete a folder

1. On the folders page, long press the folder.
2. Tap **rename**, type the new name and confirm; or tap **delete the folder**, then **delete the folder, keep the notes**.

Deleting a folder never deletes its notes: they stay in **all notes**, without a folder.

### Set up another device with the same server

1. On the device that works, open **settings** and tap **export credentials**. Choose where to send the file (your own cloud folder, for instance). The file is named `readers-credentials-notes.json` and holds the password.
2. On the other phone, open **settings**, tap **import credentials** and pick the file. The line then reads **credentials imported** and a sync starts.

The desktop app reads the same file (see "On the computer").

### Switch between white on black and black on white

Tap **⋯** on the list or in a note, then the line **black on white** or **white on black**.

## Settings

### On the phone

| Setting | What it does | Choices | At the start |
|---|---|---|---|
| **server** | Address of the WebDAV server. Emptied, the sync stops and the notes stay on the phone | text | empty |
| **username** | Login on the server | text | empty |
| **password** | Password on the server (shown as dots) | text | empty |
| **folder on the server** | Folder that holds the notes | text | Notes |
| **sync when the app opens** | Syncs each time the app comes to the front | **on** / **off** | **on** |
| **folders** | Files the notes in folders; the first page then lists them | **on** / **off** | **off** |
| **sync now** | Syncs at once; shows the last result. Present only when a server is set | – | – |
| **export credentials** | Shares a file with server, folder, username and password. Present only when a server is set | – | – |
| **import credentials** | Reads such a file | – | – |
| **careful** / **ordinary** | The speech model used for dictation; the chosen one is shown inverted | **careful** (574 MB, **recommended**, **four times slower**) / **ordinary** (190 MB) | **careful** |
| **language spoken** | The language you dictate in | the phone's language / english / **detected** | the phone's language |
| **colours** | The two colours of the app | **white on black** / **black on white** | **white on black** |
| **text size** | Size of all text | S / M / L | M |
| **font** | Typeface of all text | sans-serif / serif / mono | sans-serif |
| **haptic tick** | A short vibration when you start or stop a dictation | **on** / **off** | **on** |

Tap a line to change it: text lines open a small box to type in (**ok** to keep, **cancel** to leave unchanged); the others move to the next choice at each tap. A text line cannot be saved empty.

Under **folders** the page explains: *Notes filed in folders: the first page lists them, « all notes » first. On the server each folder is a subfolder of the notes folder. Off: all notes in one list.*

Each speech model shows its size, then **to fetch** until it is on the phone, or **fetching the model · N%** while it downloads. Choosing a model does not download it; that happens at the next dictation. If you choose **ordinary** but only **careful** is on the phone, **careful** is used.

The last two lines show the name of the app with **plain-text notes, one file each, in a WebDAV folder**, and the credits.

### On the computer

See "On the computer": the settings window holds the four server fields, **font** and **folders**; colours and text size are changed with keys.

## Your data

### Where the notes live

On the phone, notes are kept in the app's private storage. On the computer they are files in your user folder (see "On the computer"). With a server set, each note is also one `.txt` file in the folder you named, readable with any text editor. The file is named after the note's title; change the first line and the file is renamed at the next sync. A note without a title is named `untitled.txt`; two notes with the same title become `Title.txt` and `Title (2).txt`. Files ending in `.md` found in the folder are read as notes too.

### What goes over the network

- To **your WebDAV server**: the notes, with your username and password. On the phone the address must begin with `https://`.
- To **huggingface.co**, once per speech model: the download of the model. Nothing about you or your notes is sent.

Nothing else. What you dictate is turned into text on the phone.

### How the sync decides

- A note changed here and untouched on the server is sent.
- A note changed on the server and untouched here is received.
- A note changed on both sides: the server's text is kept as a second note whose title ends with **(server copy)**, and yours is sent. Nothing is overwritten without a copy.
- A note deleted here is deleted on the server, unless it changed there since; in that case it comes back as a new note.
- A note deleted on the server is deleted here, unless you changed it here since; in that case it is sent again.
- Anything new on either side crosses over.

### Folders on the server

Each folder is a subfolder of the notes folder, one level deep. A folder created here is created there; renaming it here moves its notes into a folder of the new name there. A folder deleted on the server disappears here. A folder deleted here leaves the server once no file is left in it; if someone else's files remain, it stays and comes back at the next sync. Subfolders whose name starts with a dot are ignored. Subfolders are looked at only when the **folders** setting is on, or once anything has been filed in a folder; turning the setting off afterwards shows one list again but keeps the folders in sync.

### Changing server or folder

On the phone and on the computer alike, whether you type another **server** or **folder on the server** or import a credentials file made for another place: at the next sync that reaches the new place, every note on the device is kept and sent there, with its folders, and the notes already there are received. Nothing is removed from the device, and the old folder on the old server is left as it was. A note whose file is already in the new place with the same text is not sent a second time; one with the same title and another text is sent beside it as `Title (2).txt`.

### The credentials file

**export credentials** writes a small file holding the server, the folder, the username and the password in clear. Keep it private and delete it once imported. The same kind of file is shared by Reader's Calendar, Tasks and Notes, each with its own section. If the file has no section for Notes but has one for Reader's Recorder, its server, username and password are taken (not its folder) and the app says **server and login taken from Reader's Recorder**. Colours, text size and font are never in the file.

### Dictation

The recording is kept on the phone only until its text is in the note, then deleted. If the writing was interrupted (no connection to fetch the model, the app closed), the recording waits and is taken up again the next time the app opens. The speech model is stored once and shared with Reader's Recorder, Reader's Audio Player and Reader's Podcasts when they are installed: whichever app has it lends it to the others.

### Backup and uninstalling

The phone app lets Android's own backup include its data, if you use it. Uninstalling the phone app removes the notes on the phone, the settings and the speech model it downloaded. Notes on your server are not touched.

## With the other apps

### Home-screen widgets

Three widgets work with any launcher, in the app's two colours:

- **Reader's Notes · latest note** (one line): the title of the most recent note, with when it changed and its next line. Tap it to open that note; tap **+** for a new note. Without notes it reads **no note yet**.
- **Reader's Notes · latest notes** (a list, resizable): the word **notes** (tap to open the app), **+** for a new note, and the notes, most recent first. Tap one to open it.
- **Reader's Notes · one note** (about half a screen): when you place it, a page titled **note to show** lists your notes; tap one, or **+ new note** to start a fresh one and write it at once. The widget then shows that note's title and text, like a post-it, and follows every change. Tap it to write. If the note is deleted, the widget reads **this note was deleted**. From the widget's own menu (in Reader's Launcher: **configure**), you can choose another note; the current one is marked ●.

### Reader's Launcher

Reader's Launcher shows the latest notes on its notes tile and can open a note, start a new one, or start a new one with the microphone open. Only apps signed by the same author may read the notes this way.

### Other links

- **Share menu**: Reader's Notes appears in the share menu of other apps for plain text, and shares its own notes as plain text.
- **Speech model**: shared with Reader's Recorder, Reader's Audio Player and Reader's Podcasts.
- **Credentials file**: understood by the desktop app; a Reader's Recorder file can supply the server and login.

## On the computer

### How it differs from the phone

The list and the page sit side by side in one window. There is no dictation, no **share**, no **call … / write to … / open …** lines and no widget. The sync has no on/off switch: with a server set it runs when the window opens, every two minutes, 20 seconds after you stop typing, when you move to another note or another window, when you quit, and on demand. The app starts **black on white**.

### The window

- **find** field at the top left: the list narrows as you type and always searches all notes. **Enter** opens the first match, the **Down** arrow moves into the list, **Esc** clears the search.
- **The list**: click a note to open it. The app reopens the note you were last in.
- **+ new note** under the list. You can also just type on the empty page: that starts a note.
- **Status line**: **syncing…**, **synced 09:33 1↑ 2↓**, or the error; click it to sync (or to open the settings when no server is set). **⚙** opens the settings.
- **⋯** above the page: **+ new note**, **find**, **sync now** (with a server), **delete this note**, **white on black** or **black on white**, **settings**.
- **Right click on a note**: **move to** (with folders on; the current place is marked **●**, **no folder** first) and **delete**. Right click on the empty part of the list: **+ new note**. Right click on **all notes** or **+ new folder**: **+ new folder**.

A note is saved a moment after you stop typing. An empty note is dropped when you leave it. Deleting has no confirmation. A page open on screen follows the server when you are not typing in it; if the server's version arrives while you are typing, it is kept as a second note ending in **(server copy)**.

### Folders on the computer

In the settings, tick **file the notes in folders**. The list then starts with the folders: **all notes**, each folder with its count, **+ new folder**. Click one to open it; the line **← …** above the find field goes back to the folders. New notes go into the open folder. Right click a folder for **rename…** and **delete the folder** (the app asks *Delete the folder “…”? Its notes stay in “all notes”.*). Click **+ new folder** and type the **name of the new folder**.

### The settings window

Opened with **Ctrl+,**, **⚙**, or **⋯** then **settings**.

| Field | What it does | At the start |
|---|---|---|
| **server** | Address of the WebDAV server (the field shows a kDrive address as an example) | empty |
| **username** | Login | empty |
| **password** | Password | empty |
| **folder on the server** | Folder holding the notes | Notes |
| **font** | **sans-serif**, **serif** or **mono** | sans-serif |
| **folders** › **file the notes in folders** | Shows the folders at the top of the list | unticked |
| **import credentials…** | Reads a credentials file and applies it at once | – |
| **export credentials…** | Writes this app's saved server settings into a credentials file; if the file already holds other Reader's apps, they are kept | – |

**save** keeps the changes and syncs; **cancel** leaves everything as it was. Press **save** before exporting if you have just typed new values. The bottom line shows the version.

### Keys

| Key | Effect |
|---|---|
| Ctrl+N | new note |
| Ctrl+F | go to the find field |
| Alt+Up / Alt+Down | previous / next note |
| Ctrl+T | switch between white on black and black on white |
| Ctrl+= or Ctrl++ / Ctrl+- | larger / smaller text (9 to 24 points, 13 at the start) |
| F5 or Ctrl+R | sync now |
| Ctrl+, | settings |
| Ctrl+Q | quit |

### Command line

- `readers-notes --export-credentials FILE` writes the credentials file without opening the window.
- `readers-notes --import-credentials FILE` reads one.

### Where things are kept

| System | Notes and settings |
|---|---|
| Linux | `~/.local/share/readers-notes/` for the notes, `~/.config/readers-notes/config.json` for the settings |
| Windows | `%APPDATA%\Readers Notes\` |
| macOS | `~/Library/Application Support/readers-notes/` |

The settings file holds the password and is readable by your user account only.

## Limits

- Plain text only: no formatting, no images, no attachments, no checklists, no reminders.
- No bin and no undo for a deleted note; no confirmation before deleting a note.
- Folders are one level deep. A folder name keeps at most 60 characters; the characters `\ / : * ? " < > |` are replaced by spaces. A name already taken is refused without a message.
- The title is the first non-empty line, up to 80 characters.
- On the phone, a note is moved to a folder from its long press in the list, not from the open note.
- On the phone, the server address must be `https://`.
- On the phone, **username**, **password** and **folder on the server** cannot be emptied, only replaced. The **server** line can be emptied, which stops the sync.
- Dictation exists on the phone only. Languages offered: the phone's language, English, or **detected**. The app keeps the phone awake for up to two hours of recording.
- The sync is with a WebDAV folder only; there is no other cloud service and no sharing of a note between people other than through that folder.
- Sorting is fixed: most recently changed first.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **on this phone only — tap to set up a WebDAV folder** / **on this computer only — Ctrl+, to set up a WebDAV folder** | No server is set. The notes stay on this device. Nothing to do unless you want the sync. |
| **syncing…** | A sync is running. |
| **synced 21:03 2↑ 1↓ 1−** | The last sync worked, at that time: notes sent, received, deleted. |
| **✎** on a note's small line | The note has changes not yet on the server. They go at the next sync. |
| **wrong username or password** | The server refused the login. Check **username** and **password**; with two-factor authentication use an application password. |
| **sync failed: …** / **sync failed** | The sync stopped; the words after the colon come from the system or the server (for instance no connection, or an address that does not exist). Check the **server** address and the connection, then **sync now**. |
| **this phone cannot send … to the server** | The phone's system cannot make a request the sync needs. The sync cannot work on this phone. |
| **cannot reach the server** (computer) | No connection, or a wrong address. |
| **the server refused: …** (computer) | The server answered with an error; check the address and the folder. |
| **not a WebDAV folder at this address** (computer) | The address answers, but not as a WebDAV server. Check **server**. |
| **… (server copy)** at the end of a title | The note was changed on two devices; this one holds the server's text. Compare the two notes, keep what you want, delete the other. |
| **nothing found** | No note contains the searched words. |
| **no app for this on the phone** | No app can handle the number, address or link you tapped. |
| **dictating needs the microphone** | The microphone was refused. Allow it in Android's settings for the app, then tap **● dictate** again. |
| **the microphone cannot be opened** | The phone did not give the microphone (another app may be using it). Try again. |
| **fetching the model · N%** | The speech model is being downloaded; an interrupted download carries on from where it stopped. |
| **transcribing · N%** | What you said is being written. |
| **nothing was heard** | The recording held no speech. |
| **not written yet: …** | The writing failed (often: no connection to fetch the model). The recording is kept and tried again the next time the app opens. |
| **the model cannot be read** | The speech model file cannot be opened. Dictate again; pick the other model in the settings if it persists. |
| **stopped** | The writing was interrupted. |
| **credentials imported** | The file was read; server, folder, username and password are set. |
| **server and login taken from Reader's Recorder** | The file had nothing for Notes; the Recorder's server and login were used. Check **folder on the server**. |
| **not a Reader's credentials file** | The file is not a credentials file. Pick the right one. |
| **this file holds nothing for Reader's Notes** (on the computer: **… for readers-notes**) | It is a credentials file, but with no section this app can use. |
| **the file cannot be read: …** / **cannot use this file: …** | The file could not be opened or written. |
| **credentials exported to … — the file holds your passwords: keep it private** (computer) | The export worked; the file is at the place shown. |


# Reader's Books

*Android 1.3.1*

## What it is

Reader's Books is a shelf of e-books and a reader for them, made for e-ink phones. The shelf is a plain list; a book is shown as pages of text cut at whole lines, turned by a tap, with no scrolling and no animation. It reads EPUB, MOBI, FB2 and plain-text files, shows the pictures of EPUB books inside the page, and remembers your place in every book.

The app is black and white only, with no icons. It has no store, no account and no network access at all: you bring your own files. It deliberately keeps only the text and the pictures of a book: the book's own fonts, colours, layout and links are dropped. It does not read PDF.

The app is available in English, French, German, Spanish, Portuguese and Russian; it follows the language of the phone.

## First start

The app asks for nothing at first start: no permission prompt, no account, no server.

You see the shelf, titled **books**, with this message: **nothing on the shelf. Open an epub, mobi, fb2 or plain-text file: from here, from a file manager, or by sharing it to this app.** At the bottom of the screen is the line **+ open a book**.

Tap **+ open a book**, choose a file in the phone's file chooser, and the book opens on its first page.

## The screens

### The shelf (**books**)

The shelf lists your books, one per entry, the most recently opened (or added) first. Each entry shows:

- the title of the book (two lines at most);
- a smaller line with three items separated by dots: how far you are, as a percentage of the whole text (or **not started** if you have never opened it); when you last opened it (the time for today, **yesterday**, or the date); and the format (epub, mobi, fb2 or txt).

Controls:

- **Tap a book**: opens it at the page where you left it. A magazine issue opens on its contents instead (see "The contents of a magazine").
- **Long press a book**: opens a menu headed by the book's title, with **read** (open at the current page), **chapters** (the list of chapters; for a magazine this entry is called **contents**) and **remove from the shelf**.
- **+ open a book**, at the bottom: opens the phone's file chooser to add a book.
- **⋯**, at the top right: opens the shelf menu, with **+ open a book**, then the colour switch (it reads **black on white** when the app is white on black, and **white on black** when the app is black on white; tapping it switches), then **settings**.

A menu is closed by tapping outside it or with the phone's back button.

While a file is being added, a line **…** appears at the top of the list. If the file cannot be read, the line **this file could not be read** appears there instead.

### The page (reading a book)

The whole screen is the page:

- at the top, in small print, the title of the book;
- the text, and the pictures for EPUB books;
- at the bottom left, the title of the current chapter (nothing if the chapter has no title);
- at the bottom right, the page number within the current chapter and your position in the whole book, for example **3/12 · 45%**: page 3 of the 12 pages of this chapter, 45% of the book.

A very long chapter is cut into several parts. The second and following parts carry the chapter's title followed by a dot and a number (**· 2**, **· 3**…), and the page count is that of the part.

Controls:

- **Tap the right half of the screen**: next page. On the last page of a chapter, it goes to the first page of the next chapter.
- **Tap the left half of the screen**: previous page. On the first page of a chapter, it goes to the last page of the previous chapter.
- **Long press anywhere**: opens the book's menu.
- **The phone's back button**: leaves the book and returns to the screen you came from (the shelf, or the contents of a magazine).

The book's menu is headed by the book's title and has these entries:

| Entry | What it does |
|---|---|
| **chapters** | Opens the list of chapters. For a magazine the entry is **contents** and opens the contents of the issue. |
| **larger text** | Raises the reading size by 2. The line beneath shows the change, for example **20 → 22**. The largest size is 40. |
| **smaller text** | Lowers the reading size by 2. The line beneath shows the change, for example **20 → 18**. The smallest size is 12. |
| **remove from the shelf** | Removes the book and returns to the shelf. There is no confirmation. |
| **books** | Leaves the book, like the back button. |
| **black on white** / **white on black** | Switches the colours of the whole app. |

How the text is laid out: paragraphs are aligned on the left, without hyphenation; a paragraph that follows another is indented. Headings are larger and bold. In books and magazines that mark them, the lead paragraph is bold, and the section name, the author, captions and credits are smaller and grey. A page never ends in the middle of a line.

Pictures (EPUB only) are scaled to the width of the text, centred, and never cut: a picture that does not fit in what is left of the page moves whole to the next page, and a picture taller than the page is reduced to the height of the page. Very small pictures (less than 48 pixels wide or high) are left out.

### The chapters

This screen is headed by the title of the book, with an arrow **←**; tapping that line goes back, like the phone's back button.

It lists the chapters of the book. The chapter you are in is shown in inverted colours. Tap a chapter to go to its first page.

The titles come from the book's own table of contents; failing that, from the first heading of the chapter; failing that, the chapter is shown as a number. A plain-text file has a single entry, named after the book.

### The contents of a magazine

A magazine issue is an EPUB file whose contents page gives a section, a title and an author for each article. The app recognises such a file by itself and treats each article as a chapter.

The contents screen is headed by the title of the issue, with an arrow **←** to go back. It lists the articles under their section names (in small print, in capitals). Each article shows its title, its author if there is one, and on the right a small square of its first picture if it has one. Once you have started reading the issue, the article you are in is shown in inverted colours.

- **Tap an article**: opens it on its first page.
- In the article, pages turn as in a book; after the last page of an article, a tap on the right goes on to the next article.
- **The phone's back button** in an article returns to the contents.

### Settings (**settings**)

Reached from the shelf: **⋯**, then **settings**. The screen is headed **settings** with an arrow **←**; tapping that line goes back. Each line shows the current value in large print and the name of the setting beneath it; tapping the line changes the value. See the "Settings" section for the list.

At the bottom, two lines give information only: **Reader's Books** with **reads epub, mobi, fb2 and txt files**, and **Pierre Gallaz · developed with Claude Code**.

## How to

### Add a book from the app

1. On the shelf, tap **+ open a book** (at the bottom, or in the **⋯** menu).
2. In the phone's file chooser, tap the file.
3. The book is copied onto the shelf and opens. A magazine issue opens on its contents.

One file is added at a time.

### Add a book from a file manager

1. In your file manager, tap an EPUB, MOBI, AZW, AZW3, FB2 or text file.
2. If the phone asks which app to use, choose **Reader's Books**.
3. The book is copied onto the shelf and opens.

### Add a book by sharing it

1. In the app that holds the file, choose its share function.
2. Choose **Reader's Books** in the list.
3. The book is copied onto the shelf and opens.

Sharing works for EPUB, MOBI and FB2 files. A plain-text file cannot be shared to the app: open it from the shelf or from a file manager.

### Read and turn pages

1. On the shelf, tap the book.
2. Tap the right half of the screen for the next page, the left half for the previous page.

### Carry on where you left off

Tap the book on the shelf: it opens at the page where you left it. The book you read last is at the top of the shelf. You can also use the home-screen widget or the book tile of Reader's Launcher (see "With the other apps").

### Go to a chapter

1. In the book, long press the page.
2. Tap **chapters**.
3. Tap the chapter.

From the shelf: long press the book, then **chapters**, then the chapter.

### Read a magazine issue

1. On the shelf, tap the issue: its contents open.
2. Tap an article.
3. Press the phone's back button to return to the contents, or keep tapping on the right to pass to the next article.

To return to the contents from an article you can also long press the page and tap **contents**. To go straight back to the page where you stopped, long press the issue on the shelf and tap **read**.

### Make the text larger or smaller

1. In the book, long press the page.
2. Tap **larger text** or **smaller text**. Each tap changes the size by 2, between 12 and 40.
3. Repeat if needed: the menu closes after each choice.

Your place in the book is kept when the size changes. The same adjustment is in **settings**, where **automatic size** returns to the size chosen from the width of the screen.

### Switch between white on black and black on white

On the shelf, tap **⋯** then **black on white** or **white on black**. In a book, long press the page and tap the same entry. In **settings**, tap the **colours** line.

### Change the font

1. On the shelf, tap **⋯**, then **settings**.
2. Tap the **font** line until the font you want is shown: **sans-serif**, **serif** or **mono**.

The font applies to the page as well as to the shelf and menus.

### Remove a book

1. On the shelf, long press the book (or, in the book, long press the page).
2. Tap **remove from the shelf**.

The book is removed at once, without confirmation. Only the copy kept by the app is deleted, along with your place in it; the file you added it from is not touched.

### Replace a book with a newer file

Add the new file like any book. If a book with the same title and the same format is already on the shelf, the new file takes its place and your reading position is kept.

### Put the current book on the home screen

1. Long press an empty place on your home screen and choose to add a widget (the wording depends on your launcher).
2. Choose **Reader's Books · current book**.
3. Tap the widget to carry on reading.

## Settings

All settings are on the **settings** screen (shelf, **⋯**, **settings**).

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **colours** | The colours of the whole app and of the widget. Tap to switch. | **white on black**, **black on white** | **white on black** |
| **reading size — tap for larger** | The size of the text in the page. Each tap adds 2, up to 40. The line shows the size, followed by **· auto** while the automatic size is in use. | 12 to 40 | automatic |
| **smaller text** | Lowers the reading size by 2, down to 12. The line beneath shows the change, for example **20 → 18**. | — | — |
| **automatic size** (**from the screen width**) | Returns the reading size to the automatic one, worked out from the width of the screen: between 17 and 24. | — | in use |
| **font** | The typeface of the page, the shelf and the menus. Tap to pass to the next one. | **sans-serif**, **serif**, **mono** | **sans-serif** |
| **size of the shelf and menus** | The size of the text everywhere except in the page. Tap to pass to the next one. | **S**, **M**, **L** | **M** |
| **keep the screen on while reading** | While a page is open, the screen does not switch off by itself, until fifteen minutes after the last page turn. When **off**, the phone's usual screen timeout applies. | **on**, **off** | **on** |
| **haptic tick** | A short vibration when a long press on the page opens the book's menu. | **on**, **off** | **on** |

## Your data

Everything stays on the phone. The app has no network permission: nothing is sent anywhere and nothing is downloaded. The only permission it uses is vibration, for the **haptic tick**; the phone does not ask you to grant it.

When you add a book, the app makes its own copy of the file in its private storage. You can then move, rename or delete the original: the book stays on the shelf. Next to the copies, the app keeps the list of books with, for each, its title, its format, the date it was last opened and your place in it, and your settings.

Your place is recorded at every page turn, as a position in the text and not as a page number: it stays right when you change the reading size, the font or the orientation of the screen.

There is no sync between devices, no export and no import of the shelf. The app does not exclude itself from Android's own backup; whether that backup runs depends on your phone and its settings.

Uninstalling the app deletes the copies of the books, your reading positions and your settings. The original files, where you kept them, are not touched.

## With the other apps

### Home-screen widget

The app offers one widget for any launcher: **Reader's Books · current book** (described as **the book you were reading; tap to carry on**). It is one row high, four cells wide, and can be made wider or narrower.

It shows the title of the book you opened last and, beneath, **book** followed by your position, for example **book · 45%**. Tap it to open that book at its current page. When the shelf is empty it shows **open a book** above **books**, and a tap opens the app.

The widget uses the colours chosen in the app. It is updated at every page turn.

### Reader's Launcher

Reader's Launcher can show a **book** tile with the book being read and your position; tapping it opens the book at its current page in Reader's Books. Only Reader's Launcher can read the shelf this way: other apps cannot see your list of books.

### Opening and sharing files

Reader's Books offers itself in the phone's "open with" list for EPUB, MOBI, AZW, AZW3, FB2 and plain-text files, and in the share list for EPUB, MOBI and FB2 files. In both cases the file is copied onto the shelf and opened.

## Limits

- No PDF, and no comics or audio-book formats. A file that is not recognised as EPUB, MOBI or FB2 is taken for plain text: a PDF added by mistake lands on the shelf and shows unreadable characters. Remove it.
- MOBI means the classic format, uncompressed or with standard PalmDoc compression. Files with copy protection (DRM) or with the other compression (HUFF/CDIC) are refused.
- Pictures are shown for EPUB only. Pictures in MOBI and FB2 files are left out.
- Plain-text and FB2 files are read as UTF-8. A plain-text file is one chapter; its title is the file name without the extension, with underscores replaced by spaces; paragraphs are separated by blank lines.
- The book's own styles are dropped: fonts, colours, italics, alignment, tables as grids. Links, including footnote links, cannot be followed.
- Pages are turned by tapping only: there is no swipe and no page turning with the volume buttons.
- No search in a book, no bookmarks, no highlights, no notes, no dictionary.
- No folders, no sorting choice and no search on the shelf: the order is always most recently opened first.
- Two books with the same title and the same format cannot be on the shelf together: the second replaces the first.
- One file is added at a time.
- No sync, export or import of the shelf and reading positions.

## Messages and problems

| Message | Meaning | What to do |
|---|---|---|
| **nothing on the shelf. Open an epub, mobi, fb2 or plain-text file: from here, from a file manager, or by sharing it to this app.** | The shelf is empty. | Tap **+ open a book**. |
| **…** | On the shelf: a file is being copied and read. In a book: the book is being opened. | Wait a moment. |
| **this file could not be read** on the shelf | The file you just added is not a book the app can read: damaged file, protected or unusually compressed MOBI, a file with no text in it, or a file the app was not allowed to read. Nothing was added. The line stays until another file is added successfully. | Try another copy of the book, or the same book in another format. |
| **this file could not be read** in place of the page | The app's copy of this book can no longer be opened. | Press the phone's back button, long press the book on the shelf, tap **remove from the shelf**, then add the file again. |
| **not started** | You have not opened this book yet. | — |

Other situations:

- **The book shows strange characters.** The file is probably not a supported format (a PDF, for example), or it is a text or FB2 file that is not in UTF-8. Remove it and use an EPUB, or convert the file to UTF-8.
- **The screen switched off while reading.** With **keep the screen on while reading** set to **on**, the screen stays on for fifteen minutes after the last page turn, then the phone's usual timeout applies again. Turn a page to start the fifteen minutes anew.
- **In a magazine, books in the menu does not go to the shelf.** When the article was opened from the contents, **books** returns to the contents, like the back button; press back once more to reach the shelf.


# Reader's Bookshop

*Android 1.2.1*

## What it is

Reader's Bookshop searches several free e-book catalogues at once (Project Gutenberg, Standard Ebooks, Wikisource, Bibliothèque numérique romande, Ebooks libres et gratuits, textos.info, the Internet Archive) and saves the file you choose to the phone. When a catalogue gives the author's dates, the app tells you whether the seventy years of Swiss and European copyright have passed. It is black and white, text only, with no account and nothing hosted by the app: a search goes from your phone to the site, the file comes from the site to your phone.

It does not read books: the file is handed to Reader's Books or to any other reading app. It does not decide for you whether you may download a book; it says what it knows and leaves the decision to you. One further source, Anna's Archive, is off unless you turn it on yourself after reading the warning the app shows.

The app's texts follow the phone's language: English, French, German, Spanish, Portuguese or Russian (English for any other language). There is no language setting for the interface inside the app.

## First start

The app runs on Android 8.0 and later. It asks for no permission; it only uses the internet connection.

At the first start you see a single screen, **before the first search**, with the terms of use. They say, in short:

- the app is a search tool, like a web browser; it hosts no book, stores no catalogue and keeps no account;
- copyright differs by country: in Switzerland and in the European Union a text is free seventy years after its author's death, elsewhere the rules differ, so a book offered freely by a foreign site may still be protected where you are;
- you undertake to download only what you have the right to download where you are, and you alone are responsible for it;
- nothing is sent anywhere but to the sites you search; no statistics, no tracking, no logs.

Tap **I understand and accept** at the bottom. There is no other way past this screen. You can read the same text again later in **settings** → **terms of use**.

You then arrive on the **bookshop** screen, empty, with this text: "nothing here yet. Search for a book: the file appears in this list and in the phone's Download folder, ready for any reading app."

## The screens

On every screen except the bookshop, the title line at the top starts with **←**: tap it (or use the phone's back gesture) to go back. Menus and questions appear as a sheet at the bottom of the screen; tap outside the sheet or go back to close it without choosing.

### bookshop

The home screen: the list of the files you downloaded, newest first. Each line shows:

- the title;
- the author, the source and the format (for example "Project Gutenberg · epub");
- the state: the file's size and the time or date of the download when it is finished, or **waiting**, **finding the file…**, **downloading 42%**, **failed:** followed by the reason, or **file gone from the phone** when the file has been deleted or moved outside the app.

Controls:

- **Tap a finished line**: opens the file in a reading app.
- **Tap a line that is not finished** (waiting, downloading, failed, file gone), or **long-press any line**: opens the line's menu, with **open in a reading app** and **share** (finished files only), **try again** (a failed download, as long as the app has not been closed since), then **delete the file** (finished files) or **remove from the list** (the others). From this menu the deletion is immediate, without a question.
- **↗** at the end of a finished line: shares the file with another app.
- **×** at the end of every line: for a finished file, asks **delete this file from the phone?** with **delete the file** and **cancel**; for any other line, offers **remove from the list** and **cancel**.
- **+ search for a book** at the bottom: opens the search screen.
- **⋯** at the top right: the menu.

The **⋯** menu:

| Entry | What it does |
|---|---|
| **+ search for a book** | Opens the search screen. |
| **open the folder** (under it: **files in Download/Reader's Bookshop**) | Opens the folder of the downloaded files in the phone's file manager, or the phone's downloads screen if the folder cannot be opened directly. |
| **delete all files** | Shown only when the list is not empty. Asks **delete all N files from the phone?**, then **delete all files** or **cancel**. Every line goes, finished or not. |
| **sources** | Opens the sources screen. |
| **black on white** / **white on black** | Switches the colours at once; the entry names the colours you would get. |
| **settings** | Opens the settings screen. |

### search

From top to bottom:

- **The language line**, with **language of the search** under it: English, français, Deutsch, español, português, русский. Each tap moves to the next language. It decides which sources are asked and which language the books are in. At first it is the phone's language if it is one of the six, English otherwise.
- **The text field**, with the hint **title or author**.
- **The status line and the results** (see below).
- **search** at the bottom. The search key of the keyboard does the same. Nothing happens while the text field is empty.

Tapping **search** opens the sheet **before this search**. It reads: "I will download only books I have the right to download where I am: public domain, free licence, or a book I own where the law allows a copy. I am responsible for it." Tap **☐ I take this responsibility** so that it becomes **☑ I take this responsibility**, then **search**. The box is empty again at every search; **cancel** closes the sheet without searching.

While the search runs, the top of the list shows **searching…**, then **searching… · 3 of 7 sources answered**. Under it, one line per source says where it is: **searching…** (with the seconds elapsed after five seconds, as in "searching… 12 s"), **nothing**, **4 found**, or the reason it failed (for example **timed out**). At the end the status line reads **7 of 7 sources answered**, or **nothing found in the sources that answered · …**, or **no connection**.

The results follow, grouped in the fixed order of the sources, ten at most per source. Each result shows the title, then the author and a detail that depends on the source, then the name of the source:

| Source | Detail shown |
|---|---|
| Project Gutenberg | the book's number, as "#1234" |
| Standard Ebooks | "epub · azw3" |
| Wikisource | **N words on the first page** or **contents page**, then the beginning of the text |
| Bibliothèque numérique romande, Ebooks libres et gratuits, textos.info | the formats offered |
| Internet Archive | the year, then **scan** |
| Anna's Archive | format, size, year, publisher |

**Tap a result** to see what can be downloaded. A sheet may show **…** for a moment while the app asks the site, then:

- at the top, the rights line (see "Understand the rights line" below);
- one line per file: **download epub**, **download pdf**, **download txt**… with a note under it (the size, the kind of edition, **plain text**, **epub built from the pages**, or simply the name of the source). Tap one: the download starts and the result gets a **✓** after the source's name;
- **no file offered for this title** when the site has none;
- **open the page in the browser**: the book's page on the site.

The results stay when you go back to the bookshop and return to the search.

### sources

The list of the catalogues the app can search. Each line shows the name, then **on** or **off**, the languages it covers (en fr de es pt ru) and a sentence on how the app uses the site and what its terms allow. **Tap a line** to switch the source on or off. All are on at first, except Anna's Archive.

| Source | Languages | What the app says about it |
|---|---|---|
| Project Gutenberg | all six | Catalogue made for reading apps; one request per search and per book. Public domain in the USA; in Switzerland and the EU, the author's dates decide. |
| Standard Ebooks | English | Public search page and download links, used as a browser would. The files are dedicated to the public domain (CC0); the texts are public domain in the USA. |
| Wikisource | all six | Searched the way Wikimedia asks apps to. Volunteers check that each text is in the public domain (author dead for more than 70 years) or freely licensed. |
| Bibliothèque numérique romande | French | Public catalogue of a Swiss association; every book is in the public domain (author dead for more than 70 years). |
| Ebooks libres et gratuits | French | Public catalogue. Public domain texts (author dead for more than 70 years). |
| textos.info | Spanish | Public catalogue. Public domain texts. |
| Internet Archive | all six | Public search; books only available for lending are left out. Mostly scanned books; rights as stated by whoever uploaded them. |
| Anna's Archive | all six | Shadow library aggregating Library Genesis, Z-Library and others; most of its files are copyrighted. Only its public pages are read, as a browser does. Off unless you turn it on, and then only for files you have the right to download. |

When Anna's Archive is on, a block appears under the list:

- **mirrors · found on Wikipedia, fastest first**: the site's current addresses, each with its response time (**120 ms**), **unreachable** or **not tested**. The app takes the addresses from the Wikipedia article on Anna's Archive (at most once a day) and measures their speed (at most once an hour) when you search.
- **test the mirrors now**: fetches the list and measures again at once; the line shows **…** meanwhile.
- **add a mirror**: asks for an **address, https://…**. An address that does not begin with https:// is ignored.
- the key line, **membership key (fast downloads, optional)**: shows **none**, or four dots and the last four characters of the key. Tap it to type or change the key.
- **log**: the last things the sources did, kept in memory only until the app is closed. The last twelve lines are shown under it; tap **log** (**tap to share the last lines**) to send the lines as text to another app. **none** when there is nothing yet.

At the bottom, **other sites, in the browser**, followed by the language of the search: sites worth knowing that the app does not search. Tap one to open it in the browser. The list changes with the language of the search:

| Language | Sites (and the note shown under each) |
|---|---|
| French | Nos Livres (catalogue of the French public-domain ebook sites) · Bibliothèque électronique du Québec (public domain, Québec) · Bibebook (public domain epubs) · Efele.net (carefully made epubs) · Atramenta (public domain and Creative Commons) · Gallica (Bibliothèque nationale de France) · Les Classiques des sciences sociales (social sciences, Québec) · Libre Théâtre (plays) · Bibliothèque numérique TV5MONDE (classics) · e-rara (Swiss early printed books) |
| English | Faded Page (public domain in Canada: often not in Switzerland or the EU) · Project Gutenberg Australia (public domain in Australia) · Global Grey (public domain epubs) · Planet eBook (classics) · OpenStax (free textbooks) · Freeditorial (classics and contemporary authors) |
| German | e-rara (Swiss early printed books) · Projekt Gutenberg-DE (the largest German corpus; asks to be read in a browser) · Zeno.org (literature and philosophy) · TextGrid Repository (German literature, CC-BY) · Deutsches Textarchiv (1600–1900) · Ngiyaw eBooks (public domain epubs) |
| Spanish | Biblioteca Virtual Miguel de Cervantes (the Hispanic reference) · Elejandría (public domain epubs) · Ganso y Pulpo (carefully made epubs) · Freeditorial (classics and contemporary authors) |
| Portuguese | Domínio Público (Brazilian government library) · Biblioteca Nacional Digital (Biblioteca Nacional de Portugal) · Projeto Livro Livre (public domain epubs) · Literatura Brasileira (UFSC) (Brazilian literature) |
| Russian | Lib.ru (the classics before 1917) · ФЭБ (scholarly editions) · Русская виртуальная библиотека (annotated editions) · ilibrary.ru (classics) · Tolstoy.ru (the 90 volumes, free) |
| All six | DOAB (open access academic books) · OpenEdition Books (open access, humanities) · Open Library (borrowing of digitised books, with an account) |

### settings

See "Settings" below. The screen also holds **sources** (the sources screen), **export credentials**, **import credentials**, **terms of use**, and at the bottom the app's name and version with **searches free ebook catalogues and saves the books to the phone**, and the credits.

### before the first search (terms of use)

The text accepted at the first start. Opened from **settings** → **terms of use**, it ends with **ok**.

### browser check

This screen only appears with Anna's Archive. It shows a page of the site inside the app, in two cases:

- the site wants to check that a browser is visiting. The screen says: **the site wants to see a browser; when the page shows, the app carries on by itself**. If the page asks you something (a box to tick, a puzzle), answer it;
- a download page with a countdown. The screen says: **a download page: the countdown runs here, then the file follows**.

The app first tries to pass these pages by itself, out of sight; the screen is shown only when that is not enough. It closes by itself when the page is through. Tapping **← browser check** or going back gives up: the search or the download then fails with **browser check not passed**, and the app does not show the check again for one minute.

## How to

### Find and download a book

1. On the bookshop, tap **+ search for a book**.
2. Tap the language line until it shows the language of the book.
3. Type a title or an author in **title or author**.
4. Tap **search**.
5. Tap **☐ I take this responsibility**, then **search**.
6. Wait for the sources to answer, then tap a result.
7. Read the rights line at the top of the sheet.
8. Tap **download epub** (or another format).
9. Tap **← search** to return to the bookshop: the book is at the top of the list, with its progress.

You can start several downloads one after the other; they go on while you use the other screens of the app.

### Understand the rights line

The line at the top of the sheet of a result says what the app knows:

| Line | Meaning |
|---|---|
| **public domain in Switzerland and the EU: the author died in 1910** | The source gives the author's dates and more than seventy years have passed since the year of death. |
| **the author died in 1980: still protected in Switzerland and the EU** | The source gives the dates and the seventy years have not passed. The app still lets you download: the decision is yours. |
| **rights not stated: check before downloading** | The source gives neither dates nor a statement. |
| **public domain in the USA; files CC0** | Standard Ebooks. |
| **public domain, life + 70 years (BNR)** | Bibliothèque numérique romande. |
| **public domain (ELG)**, **public domain (textos.info)** | Ebooks libres et gratuits, textos.info. |
| **Wikisource** | A Wikisource text; see what the sources screen says about it. |
| **unknown: check yourself** | Anna's Archive. |

For Project Gutenberg, when the author's dates are missing, the line shows the rights statement sent by the site, in the site's own words. Author's dates come from Project Gutenberg and, when the record has them, from the Internet Archive.

### Read a downloaded book

Tap its line on the bookshop. The phone opens it in the reading app set for that kind of file, or asks which app to use. You can also long-press the line and choose **open in a reading app**.

### Send a book to another app or another device

Tap **↗** at the end of the line (or long-press the line, then **share**) and choose the app: a reader, a messaging app, a cloud folder.

### Find the files on the phone

Open **⋯** → **open the folder**. The files are in the phone's Download folder, in a subfolder named Reader's Bookshop, under the name "Author - Title" followed by the format.

### Delete a book

Tap **×** at the end of its line, then **delete the file**. The file is removed from the phone and the line from the list.

### Delete everything

Open **⋯** → **delete all files**, then confirm with **delete all files**.

### Try a failed download again

Tap the failed line, then **try again**. This entry exists only while the app has stayed open since the failure. Otherwise tap **remove from the list** and search for the book again.

### Clear a line whose file is gone

A line reading **file gone from the phone** means the file was deleted or moved with another app. Tap **×**, then **remove from the list**.

### Choose which sources are searched

Open **⋯** → **sources** and tap a source to switch it **on** or **off**. Only the sources that are on and that cover the language of the search are asked.

### Look on a site the app does not search

Open **⋯** → **sources**, scroll to **other sites, in the browser** and tap a site. To see the sites for another language, change the **language of the search** first (on the search screen or in the settings).

### Turn on Anna's Archive

1. Open **⋯** → **sources** and tap **Anna's Archive**.
2. Read the warning. It says: "Anna's Archive is a shadow library: it indexes Library Genesis, Z-Library and other collections, most of which hold copyrighted books, and courts have ordered its domains blocked. Ticking a box does not change the law. Turn it on only if you will use it for files you have the right to download: public-domain texts, open-access publications, or a copy of a book you own where your law allows it. Its pages are read by the app exactly as a browser would; a browser check may appear, and a download waits for the site's countdown."
3. Tap **turn on**, or **cancel** to leave it off.

The warning is shown the first time only. Tap the line again to switch the source off; switching it back on later no longer shows the warning.

With this source on, a search can take much longer (the app waits up to two minutes for it, against twenty-five seconds for the others), and the **browser check** screen may appear. Its files are offered as **slow download 1 (waits for the countdown)**, **slow download 2…**, and **fast download 1 (members)** when the page has such links.

### Enter an Anna's Archive membership key

1. Turn the source on, then, on the sources screen, tap the line **membership key (fast downloads, optional)**.
2. Type **the key from your Anna's Archive account** and tap **ok**.

A result from this source then offers **fast download (member key)** first, without countdown. To remove the key, tap the same line and choose **cancel**: closing this prompt in any way other than **ok** removes the key.

### Set up another phone with the same key

1. On the first phone: **settings** → **export credentials**, and send the file to yourself by the app of your choice. The file holds the key in readable form: keep it private.
2. On the other phone: **settings** → **import credentials**, and pick the file. The app answers **credentials imported**.

### Send the log when Anna's Archive fails without saying why

On the sources screen, with Anna's Archive on, tap **log** and choose the app to send the text with.

## Settings

Open **⋯** → **settings**. Each line shows the current value; each tap moves to the next choice.

| Setting | Choices | At first |
|---|---|---|
| **language of the search** | English, français, Deutsch, español, português, русский | the phone's language if it is one of the six, else English |
| **colours** | **white on black**, **black on white**, **as the phone** (follows the phone's dark mode) | **white on black** |
| **font** | **serif**, **sans serif**, **monospace** | **sans serif** |
| **size** | **small**, **medium**, **large** | **medium** |
| **haptic tick** | **on**, **off** | **on** |

The **haptic tick** choice is kept, but no control of the app vibrates in this version, whichever value is chosen.

The other lines of the screen are not settings: **sources**, **export credentials** (with the note **a file to set up another phone — it holds the Anna's Archive key: keep it private**), **import credentials**, **terms of use**.

Settings found on the sources screen: each source **on** or **off** (all on, Anna's Archive off), the added mirrors and the membership key (**none** at first).

## Your data

**On the phone only.** The app has no account and no server of its own.

- The downloaded files are in the phone's shared Download folder, subfolder Reader's Bookshop, where any file manager and any reading app can reach them. On Android 9 and older they go to the app's own folder on the phone's storage instead; **open the folder** shows its path.
- The list shown on the bookshop, the settings, the choice of sources, the mirrors and the membership key are kept in the app's private storage.
- The log is kept in memory and vanishes when the app is closed.

**What goes over the network.** Always over a secure (https) connection:

- your search words and the language, to each source that is on for that language, straight from the phone; then the requests for the book you tap and for the file you download;
- to the catalogues, the app announces itself by its own name; to Anna's Archive it presents itself as the phone's built-in browser and keeps the cookies the site sets;
- with Anna's Archive on: a request to Wikipedia for the list of addresses, a speed test of each address, and, if you entered one, your membership key to the site when you choose **fast download (member key)**.

Nothing else is sent: no statistics, no tracking, nothing to the app's author.

**No sync.** Nothing is synchronised between devices. The only thing you can carry over is the membership key, with **export credentials** and **import credentials**. The exported file is a Reader's credentials file; this app reads and writes only its own part of it, and only the key. The copy prepared for sharing is erased at the next export and at the next start of the app.

**Deleting.** The app deletes only files it downloaded itself. Deleting a line from the list deletes its file. A file deleted with another app shows as **file gone from the phone**.

**Uninstalling** removes the list, the settings and the key. The files in Download/Reader's Bookshop stay on the phone (on Android 9 and older, they are removed with the app). The app does not exclude itself from Android's own backup of app data, if that is enabled on the phone.

## With the other apps

- **Reading apps.** A tap on a finished line hands the file to a reading app. Reader's Books opens epub, mobi, azw3, fb2 and txt files handed over this way, and accepts epub, mobi, azw3 and fb2 files through **↗**.
- **Sharing.** **↗** sends the file to any app that accepts files. The log and the credentials file are shared the same way.
- **Browser.** **open the page in the browser** and the **other sites** open in the phone's browser.
- **File manager.** **open the folder** opens the phone's file manager.

The app offers no home-screen widget, receives nothing shared from other apps and opens no files itself.

## Limits

- The app does not display books; it needs a reading app.
- Six search languages only: English, French, German, Spanish, Portuguese, Russian.
- Ten results at most per source and per search; there is no "more results". Make the search more precise instead.
- File types recognised: epub, mobi, azw3, fb2, txt, pdf, cbz, cbr. Other files a site may offer are not listed.
- The Internet Archive is searched by title only, among freely downloadable texts that have an EPUB; books available only for lending are left out. Many are scans.
- Bibliothèque numérique romande is searched by title; if no title matches, the books of the first matching author are shown.
- Standard Ebooks, Bibliothèque numérique romande, Ebooks libres et gratuits and textos.info each cover a single language and are not asked for the others.
- A Wikisource book is put together by the app from the pages of the site: text only, no images, 200 chapters at most. The search lists pages of the site, so a result may be a single chapter or a contents page, and the author is not shown in the results.
- The rights line covers Switzerland and the European Union (seventy years after the author's death) and only when the source gives the dates. It says nothing for other countries.
- Removing a line while its download is running does not stop the download: the file may still arrive in the folder, without a line in the list.
- A download does not survive the closing of the app: it shows **failed: interrupted** at the next start and must be started again from a new search.
- No notification is shown when a download finishes.
- A source waits at most 25 seconds (Anna's Archive: two minutes); past that it counts as **timed out**.

## Messages and problems

### On the search screen

| Message | Meaning, and what to do |
|---|---|
| **no source is on for this language: see sources in the menu** | Every source for the chosen language is off. Go back to the bookshop, **⋯** → **sources**, and switch one on. If a search does nothing at all, check this too. |
| **no connection** | The phone could not reach the sites. Check the connection and search again. |
| **nothing found in the sources that answered** | No source had the title. Try fewer words, the author alone, or another language. |
| **N of M sources answered** | Some sources did not answer; their own line says why. The results of the others are complete. |
| **timed out** (on a source's line) | The source was too slow. Search again later. |
| **browser check not passed** | Anna's Archive asked for a browser check that did not go through, or you left the check screen. Wait a minute, search again and let the page finish. |
| **too many requests, try later** | The site is limiting the number of requests. Wait before searching again. |
| **server answered 503** (or another number) | The site answered with an error. Try later. |
| **unexpected answer from the site** | The site sent something the app could not read. Try later; the site can still be reached with **open the page in the browser** or in the browser. |
| **connection failed** | The connection broke during the request. Try again. |
| **no mirror** | No address of Anna's Archive could be used. Open **sources** and tap **test the mirrors now**. |
| **no file offered for this title** | The site lists the book without a file the app can take. Try **open the page in the browser**. |
| **unknown error** | Something else went wrong. With Anna's Archive on, the **log** on the sources screen holds the detail. |

### On the bookshop

A failed line reads **failed:** followed by one of the reasons above or below.

| Message | Meaning, and what to do |
|---|---|
| **waiting** | The download is about to start. |
| **finding the file…** | The app is asking the site for the file's address, or waiting for a countdown. |
| **downloading 42%** | The file is arriving. For a Wikisource book, the figure is the share of the pages already fetched. |
| **download incomplete** | The connection dropped before the end, three times. Tap the line, then **try again**. |
| **the site sent a page, not the file** | The address led to a web page instead of the book. Try another format or another result. |
| **no download link** | The site gave no address for the file. Try again, or another result. |
| **the membership key gave no download link** | Anna's Archive did not accept the key for this file. Check the key, or use a slow download. |
| **no answer from the key** | The site did not answer the request made with the key. Try again later. |
| **page not found** | The Wikisource page no longer exists under that name. |
| **too many redirects** | The site sent the app from address to address without end. Try later. |
| **cannot create the file**, **cannot write the file** | The phone refused the file in the Download folder. Check the free space. |
| **interrupted** | The app was closed during the download. Remove the line and download again. |
| **file gone from the phone** | The file was deleted or moved outside the app. Remove the line. |

A message that comes from Anna's Archive itself may also appear as the site worded it, in English.

### In the settings

| Message | Meaning, and what to do |
|---|---|
| **no key to export yet** | There is no membership key to put in the file. Nothing else is exported. |
| **credentials imported** | The key from the file is in place. |
| **not a Reader's credentials file** | The file chosen is not a credentials file from a Reader's app, or it could not be read. |
| **this file holds nothing for Reader's Bookshop** | It is a Reader's credentials file, but without a key for this app. |

### On the sources screen

| Message | Meaning |
|---|---|
| **unreachable** | The address did not answer the last test. |
| **not tested** | The address has not been tested yet; tap **test the mirrors now**. |


# Reader's Recorder

*Android 1.10.1*

## What it is

Reader's Recorder is a voice recorder in black and white, made of text only. One tap records a memo, a lecture or a conversation, and the recording goes on with the screen off. The phone itself then writes the transcript, makes a cleaned copy that is easier to listen to and, if you turn the option on, lists the main points; none of this is sent anywhere.

You can add a folder on your own WebDAV server (kDrive, Nextcloud…) where the app copies each recording with its transcript, its cleaned copy and its main points. That folder is an export: the app never fetches anything back from it. There is no account, no advertising, and nothing goes to Google.

The app does not edit or trim recordings, does not let you correct a transcript, and does not import sound files made elsewhere.

## First start

At the first launch Android asks two permissions:

- **Microphone**: needed to record. If you refuse, the app asks again the next time you tap **● record**.
- **Notifications** (Android 13 and later): for the silent notification that stays on screen while a recording runs, with its **pause** and **stop** buttons, and for the ones shown during transcription and playback.

There is no account to create and no server to enter. The list is empty and shows **nothing recorded yet. ● below records; the notification or the widget stops.** Under it, a small line reads **on this phone only — transcribed here, nothing leaves the phone**, and the bottom row is **● record**.

The first time a recording has to be transcribed, the app downloads the transcription model (190 MB), once, over whatever connection the phone has at that moment. The progress is shown as **fetching the model · N%**.

A cloud folder is optional and can be added later from the settings (see "Set up a cloud folder").

## The screens

### The list (**recorder**)

The title line reads **recorder**, with **⋯** on the right for the menu.

Each recording is a row: the title in large type and, under it in small type, the date and time, the length, the kind (**memo**, **lecture** or **conversation**) and where it stands:

- **on this phone**: no cloud folder is set up;
- **to upload**: a cloud folder exists and the recording has not gone up yet;
- **in the cloud**: uploaded;
- **transcribed**: the transcript is written;
- while the phone works on it, the step in progress (**transcribing · N%**, **cleaning the sound**, **writing the main points, N%**…);
- if something failed, the error message instead.

A title is automatic: first the date and time, then the first words of the transcript once it exists. A title you type yourself stays. While the title is still the date, the date is not repeated under it.

Controls:

- **Tap a row**: opens the recording's page.
- **Long press a row**: opens a menu with **rename**, **share the audio**, **share the transcript** (only when there is a transcript), **delete** (with the note **here and in the cloud folder** when it has been uploaded) and **select several…**.
- **The small line above the bottom row** shows what is going on: the processing step in progress; or, with a cloud folder, the result of the last sync (**synced 21:03**, followed by the number of recordings sent and **↑**, or an error message) or **cloud folder:** and its name; or, without one, **on this phone only — transcribed here, nothing leaves the phone**. Tapping it starts a sync when a cloud folder exists, and opens the settings otherwise.
- **● record** (bottom row, inverted): starts a recording at once and opens the recording page.
- While a recording runs, its row in the list is inverted and reads **recording** with the running time, and the bottom row becomes **■ recording** with the running time. Tapping either opens the recording page; it does not stop the recording.

The **⋯** menu contains:

- **sync now** (only when a cloud folder is set up);
- the kind of the next recording (**memo**, **lecture** or **conversation**, with **kind of the next recording** under it): each tap moves to the next kind;
- **black on white** or **white on black**: switches the colours;
- **settings**.

### Selection mode

After **select several…**, each row carries a box (☐ or ☑), the title line shows **N selected** and the bottom row becomes **delete N**. Tap rows to tick or untick them; a long press also ticks. Tap **delete N** to delete all ticked recordings, on the phone and in the cloud folder. Tap the title line or press Back to leave without deleting.

### The recording page

The title line reads **recording** (or **paused**). Tapping it, or pressing Back, returns to the list while the recording goes on.

The page shows the running time in large figures, a level line that moves with the sound, the recording's title, and the kind with **tap to change** under it. Tapping the kind moves to the next one (memo, lecture, conversation); the choice also becomes the kind of the next recordings.

At the bottom: **pause** (which becomes **resume**) and **■ stop**. Stopping returns to the list. A recording shorter than half a second is discarded.

Opening the app while a recording runs leads straight to this page.

### A recording's page

The title line shows the recording's title (tap it to go back) and **⋯** for the menu.

- **The player line**: the position and the total length, and under them the date, the kind and the status. When a cleaned copy exists, the line ends with **playing the cleaned audio**: this is the copy you hear. On the right, **▶** plays and **❚❚** pauses.
- **The rule under the player** shows the position. Tap anywhere on it to jump there; if the recording was not playing, it starts from that point.
- **main points**: shown above the transcript when they have been written.
- **The transcript**, in paragraphs. When there is none yet, a line says why:
  - the step in progress, when the phone is working on this recording;
  - an error message; tap it to clear it and start again;
  - **the transcript will appear here once the phone has worked through it — tap to start now**;
  - **no transcription: it is turned off in the settings. Tap to change.**, which opens the settings.

The **⋯** menu contains, depending on the recording's state:

| Entry | When it is shown | What it does |
|---|---|---|
| **rename** | always | asks for a title |
| **share the audio** | always | sends the sound file (the cleaned copy when there is one) to another app |
| **share the transcript** | when there is a transcript | sends the text to another app |
| **upload now** | cloud folder set up, recording not uploaded yet | starts a sync |
| **try again** | uploaded, and an error is shown | clears the error and syncs |
| **transcribe now** | not transcribed yet, the phone transcribes | starts the transcription |
| **write the main points (beta)** | the option is on, its model is on the phone, the recording is transcribed and has no points | asks for the points of this recording |
| **stop** | the phone is working on this recording | stops the work in progress |
| **delete** | always | deletes the recording, on the phone and in the cloud folder |

### Settings

Opened from the list's **⋯** menu. Each row shows the current value in large type and the name of the setting under it; a tap moves to the next choice. The section "Settings" below describes every row.

### Notifications

- **While recording**: **recording** (or **paused**) with the running time, and two buttons, **pause** / **resume** and **stop**. Tapping the notification opens the app. It is silent.
- **While the phone transcribes**: the recording's title, the step in progress with a progress bar, and **stop**.
- **During playback**: the recording's title, **playing** or **paused** with the position, and two buttons, **pause** / **resume** and **stop**.

In Android's notification settings the three categories are named **recording**, **transcription** and **playback**.

## How to

### Record

1. Tap **● record** at the bottom of the list (or the ● of the widget, or the tile in Reader's Launcher).
2. Speak. You can turn the screen off or leave the app.
3. Tap **■ stop** on the recording page, **stop** in the notification, or ■ on the widget.

Starting a recording stops any playback.

### Pause and resume

Tap **pause** on the recording page or in the notification, then **resume**. The time spent paused is not counted.

### Choose the kind: memo, lecture or conversation

- For the next recordings: list **⋯** menu, tap the kind; or settings, **kind of the next recording**.
- During a recording: tap the kind on the recording page.

The kind is shown in the list and, in the cloud folder, in the file name. It also decides how the microphone is used, and this is fixed when the recording starts: a memo uses the phone's voice-oriented sound processing; a lecture or a conversation uses the microphone's raw, unprocessed sound when the phone offers it. Lecture and conversation are otherwise treated alike.

### Listen to a recording

1. Tap the recording in the list.
2. Tap **▶**. Tap **❚❚** to pause.
3. Tap the rule to move to another moment.

Playback continues with the screen off and when you leave the app. It pauses when headphones are unplugged or when another app takes the sound, and stops at the end.

### Read the transcript

Open the recording: the transcript is under the player. It is written automatically after each recording when **who transcribes** is **this phone**. To start it at once, tap the line **the transcript will appear here… — tap to start now**, or **⋯** then **transcribe now**.

### Stop a transcription in progress

Tap **stop** in the transcription notification, or open the recording and choose **⋯** then **stop**. The work starts again the next time you open the app or finish a recording. To stop transcription for good, set **who transcribes** to **nobody**.

### Get the main points

1. In the settings, tap the row **also write the main points (beta)**. The first tap downloads its model (2105 MB); the row shows **fetching the model · N%**. You can leave the screen meanwhile.
2. When the download ends, the option turns **on** by itself.
3. From then on, every new recording gets its points after its transcript. They appear under **main points** on the recording's page.
4. For a recording made before you turned the option on, open it and choose **⋯** then **write the main points (beta)**.

The points are two sentences on the subject, then a list (up to eight points for a short recording, more for a long one). A transcript of fewer than about 120 words gets none. If writing the points fails twice for a recording, the app leaves it alone until you ask again with **write the main points (beta)**.

### Rename a recording

1. Long press the row and choose **rename**, or open the recording and choose **⋯** then **rename**.
2. Type the title and tap **ok**.

If the recording is in the cloud folder, its files there are renamed too.

### Share the sound or the transcript

Long press the row (or **⋯** on the recording's page), then **share the audio** or **share the transcript**, and pick the app to send it to. The sound shared is the cleaned copy when it exists, the original otherwise.

### Delete one recording

Long press the row and choose **delete**, or **⋯** then **delete** on its page. There is no confirmation and no undo. With a cloud folder, the recording's files there are deleted as well.

### Delete several recordings

1. Long press a row and choose **select several…**.
2. Tick the others.
3. Tap **delete N** at the bottom.

### Set up a cloud folder

1. Open the settings and tap **set up a cloud folder**.
2. **server — for kDrive, just the number in its web address**: for kDrive, type the number that follows /drive/ in kDrive's web address (the app gives the example ksuite.infomaniak.com/kdrive/app/drive/123456/…). For Nextcloud or any other WebDAV server, type the full https:// address. Tap **next**.
3. **username (e-mail)**: for kDrive, the e-mail you log in to Infomaniak with. Tap **next**.
4. **password (an application password if two-factor is on)**: your password; with two-factor authentication, create an application password instead (for Infomaniak: Manager, Security, Application passwords). Tap **connect**.

The app tries the connection at once, creates a folder named **Recordings** and starts sending. **how to set it up, step by step** shows these instructions inside the app.

To use another folder, tap the folder row (**folder on the server**) and type its name. To correct the server, the username or the password, tap the server row: the three questions come back with their current answers.

### Sync by hand

Tap the small line above **● record** in the list, or **⋯** then **sync now**, or the **sync now** row in the settings. The app also syncs each time it is opened, when a recording ends and when a transcription ends.

### Stop using the cloud folder

In the settings, tap **forget the cloud folder (recordings stay here)**. The server, username and password are erased from the phone. The recordings stay on the phone, and what was already sent stays on the server.

### Copy the cloud settings to another device

1. In the settings, tap **export credentials** (**a file to set up another device or app — it contains the password**).
2. Send the file to the other device by the means you choose.
3. On the other device, in the app's settings, tap **import credentials** and pick the file.

The app answers **credentials imported**, then syncs. A credentials file exported by Reader's Notes also works: the app takes its server, username and password (not its folder) and answers **server and login taken from Reader's Notes**.

### Change the look

In the settings: **colours**, **text size**, **font**. The colours can also be switched from the list's **⋯** menu.

## Settings

Cloud folder (top of the screen):

| Row | What it does |
|---|---|
| **set up a cloud folder** (**on this phone only**) | Shown when no folder is set up. Asks the three questions. |
| server row (**server** and the username under the address) | Shown once set up. Tap to answer the three questions again. |
| folder row (**folder on the server**) | The folder's name. Default: Recordings. |
| **sync now** | Starts a sync. Shows **syncing…**, then the result of the last sync. |
| **forget the cloud folder (recordings stay here)** | Erases the server, username and password from the phone. |
| **how to set it up, step by step** | Shows or hides the instructions. |
| **export credentials** | Shown once set up. Shares a file holding server, folder, username and password. |
| **import credentials** | Reads such a file. The result is shown under the row. |

Transcription and recording:

| Setting | Choices | Default |
|---|---|---|
| **who transcribes** | **this phone**, **nobody** | **this phone** |
| quality: **ordinary** (190 MB) or **careful** (574 MB, marked **recommended**) | tap one of the two rows; the chosen one is inverted | **ordinary** |
| **also make a cleaned copy (volume, rumble)** | **on**, **off** | **on** |
| **also write the main points (beta)** | **on**, **off** | **off** |
| **language spoken** | the phone's language, English, **detected** | the phone's language |
| **kind of the next recording** | **memo**, **lecture**, **conversation** | **memo** |

Look:

| Setting | Choices | Default |
|---|---|---|
| **colours** | **white on black**, **black on white** | **white on black** |
| **text size** | S, M, L | M |
| **font** | sans-serif, serif, mono | sans-serif |
| **haptic tick** | **on**, **off** | **on** |

Notes on these settings:

- **who transcribes**: with **nobody**, recordings are neither transcribed nor cleaned and get no main points; the three rows about quality, cleaned copy and main points disappear. Going back to **this phone** starts work on every recording not yet transcribed.
- **Quality**: **ordinary** is quick; **careful** makes fewer mistakes and is much slower. A model not yet on the phone is marked **to fetch**; it is downloaded at the next transcription. Changing the quality does not transcribe again what is already transcribed.
- **also make a cleaned copy (volume, rumble)**: after the transcript, the phone makes a second sound file with the low rumble removed and the loudness brought to a steady level, without compressing the dynamics. The original is kept. The copy is what you hear and what **share the audio** sends.
- **also write the main points (beta)**: needs a phone with about 6 GB of memory. On a smaller phone the row reads **off** with **this phone has N GB: not enough** and cannot be turned on. The model needs about 2.2 GB of free storage. When Reader's Audio Player already holds the model, the row says **shared with Audio Player** and nothing is downloaded.
- **language spoken**: tells the transcription which language to expect. **detected** lets it find out by itself.
- **haptic tick**: a short vibration when you tap **pause**, **resume** or **■ stop** on the recording page.

The last two rows show the app's name with **records and transcribes on the phone; a cloud folder is optional**, and the credits.

## Your data

**On the phone.** Recordings, transcripts, cleaned copies, main points and settings live in the app's private storage. Recordings are .m4a files (AAC, 128 kb/s, 48 kHz, mono). The cloud password, if you set a folder up, is kept in the app's settings on the phone. Uninstalling the app deletes all of it, including the downloaded models; only what was copied to a cloud folder remains.

**What goes over the network.**

- The transcription model (190 MB or 574 MB) and the main-points model (2105 MB) are downloaded once from the Hugging Face website. An interrupted download carries on from where it stopped.
- If you set up a cloud folder, the app talks to that server only, over https, with your username and password.
- Nothing else. Transcription, cleaning and main points all run on the phone.

**The cloud folder.** For each recording the app puts in the folder:

- the sound, named with the date, the time and the kind, for example 2026-03-14_09-30_memo.m4a; once you have typed a title, the title replaces the kind in the name;
- a small .json file beside it (title, kind, date, length, language);
- the transcript (.txt), the cleaned copy (the name ends with _nettoye.m4a) and the main points (the name ends with .resume.txt) as soon as the phone has made them; they follow at a later sync.

Renaming a recording in the app renames its files in the folder; deleting it deletes them. A sync never deletes anything by itself and never downloads anything: changes made in the folder from elsewhere do not come back to the phone, and a new phone connected to the same folder does not receive the old recordings.

**The credentials file.** **export credentials** creates a file named readers-credentials-recorder.json with the server, the folder, the username and the password in clear. Treat it as you would the password itself. The temporary copy the app keeps for sharing is erased at the next start.

**Models shared between apps.** Reader's Recorder, Reader's Audio Player and Reader's Podcasts use the same models. When one of them already holds a model, the others read it there instead of downloading it again.

## With the other apps

### Home-screen widgets

Two widgets work with any launcher. Both follow the app's colours and are one row high.

- **Reader's Recorder** (**record with one tap, stop with the next**): shows **record** with the latest recording and its length under it, and ● on the right. Tap ● to start. While recording it shows **recording** (or **paused**), **tap ■ to stop**, the running time and ■. Tapping the text opens the app. The microphone permission must already have been given in the app.
- **Reader's Recorder · listen** (**the latest recordings: ▶ plays, ‹ › step through them**): shows one recording at a time, the latest first, with its rank (for example 1/5), its date and its length. **▶** plays and **❚❚** pauses; **‹** goes to the more recent one, **›** to the older one; tapping the title opens the recording in the app. With no recording it reads **nothing recorded yet**.

### Reader's Launcher

Reader's Launcher offers two tiles for this app: **recorder** (the same one-tap record button, with the latest recording under it) and **recordings** (listen to the recordings, swiping from the latest to the older ones). What plays from a widget or a tile is the same playback as in the app: it shows on the recording's page and in the notification.

### Sharing

The app sends sound files, transcripts and the credentials file to other apps through Android's share menu. It does not receive anything shared from other apps.

## Limits

- One recording at a time, in mono. The format (.m4a, AAC 128 kb/s, 48 kHz) cannot be changed.
- No trimming or editing of the sound, no playback speed.
- A transcript cannot be corrected or selected in the app, and speakers are not told apart. To work on the text, share it to another app.
- The main points can be read in the app and are copied to the cloud folder, but there is no entry to share them.
- A recording already transcribed cannot be transcribed again with another quality or language.
- The cleaned copy is made together with the transcript. Turning the option on later does not add it to recordings already transcribed, and nothing is cleaned when **who transcribes** is **nobody**.
- The language choice is limited to the phone's language, English and **detected**.
- No import of sound files recorded elsewhere, no search, no folders.
- The cloud folder is WebDAV only, over https, and is one-way: the phone sends, it never receives. Syncing happens when the app is opened, when a recording or a transcription ends, or by hand; there is no sync on a timer.
- Changing the folder's name does not move what was already sent, and recordings already uploaded are not sent again to the new folder.
- Main points need about 6 GB of memory and a transcript of at least about 120 words.
- Deleting has no confirmation and no undo.

## Messages and problems

Processing steps, shown in the list, on the recording's page and in the notification:

| Message | Meaning |
|---|---|
| **waiting** | The phone is about to start on this recording. |
| **fetching the model · N%** | A model is being downloaded. |
| **transcribing · N%** | The transcript is being written. |
| **cleaning the sound** | The cleaned copy is being made. |
| **writing the main points, N%** | The main points are being written. |
| **(no speech detected)** | Written in place of the transcript when no speech was found. |

Transcription and models:

| Message | What to do |
|---|---|
| **the transcript will appear here once the phone has worked through it — tap to start now** | Wait, or tap the line. |
| **no transcription: it is turned off in the settings. Tap to change.** | Set **who transcribes** to **this phone**. |
| **the model is missing — try again to fetch it** | The model disappeared from the phone. Tap the message, or **⋯** then **transcribe now**. |
| **no connection** | The phone could not reach the server. Check the connection and try again. |
| **download refused (HTTP N)** | The download site refused. Try again later. |
| **download cut short — try again to carry on** | The download stopped before the end. Try again: it carries on from where it stopped. |
| **N% downloaded · tap to continue** | The main-points model is partly downloaded. Tap the row to carry on. |
| **not enough space: N MB needed** | Free that much storage, then tap the row again. |
| **this phone has N GB: not enough** | The phone has too little memory for the main points. |
| **no sound in this file** | The recording holds no sound that can be read. |
| **transcription failed:** followed by a reason | Tap the message on the recording's page to try again. |
| **download failed:** followed by a reason | Shown on the main-points row. Tap the row to try again. |

A recording that shows an error is left alone until you tap the message on its page or choose **transcribe now** or **try again** in its menu.

If the main points do not appear for a recording, the transcript may be too short, the phone may have lacked free memory at that moment, or two attempts may have failed. Open the recording and choose **⋯** then **write the main points (beta)**.

Cloud folder:

| Message | What to do |
|---|---|
| **syncing…** | A sync is running. |
| **synced** followed by the time | The last sync succeeded. A number with **↑** counts the recordings sent. |
| **cloud folder:** followed by the name | A folder is set up; no sync has run since the app started. |
| **wrong username or password** | Tap the server row in the settings and answer the three questions again. With two-factor authentication, use an application password. |
| **the server answered with an error (HTTP N)** | Check the server address and the folder name. |
| **this phone cannot send the … request** | This phone cannot speak to WebDAV servers in the way the app needs. |
| **sync failed:** followed by a reason | Check the connection and the server address, then sync again. |
| **upload failed:** followed by a reason | Shown on the recording. Choose **⋯** then **upload now**. |

Credentials file:

| Message | Meaning |
|---|---|
| **credentials imported** | The file was read and a sync has started. |
| **server and login taken from Reader's Notes** | The file came from Reader's Notes; its server, username and password were taken. |
| **not a Reader's credentials file** | The file is not a credentials file, or cannot be read. |
| **this file holds nothing for Reader's Recorder** | It is a credentials file, but with nothing this app can use. |


# Reader's Podcasts

*Android 1.1.2 · Linux 1.1.2*

## What it is

Reader's Podcasts is a podcast player that shows only text: you subscribe to podcasts, download or stream their episodes, and listen, and every episode resumes where you left it. On the phone it can also write down what is said in an episode and translate that text, entirely on the phone, so that you read along while you listen. A twin program for the computer shows the same lists in one window.

There is no account, no server, no artwork, no recommendations and no store. Two files you export and import yourself (the subscriptions and the settings with the listening positions) are the whole synchronisation between the phone and the computer.

The Android app runs on Android 10 and later. Both programs exist in six languages: English, French, German, Spanish, Portuguese and Russian. The Android app does not handle YouTube; the computer program does, with the help of a separate tool.

In this chapter a podcast you follow is called a **channel**, as in the app.

## First start

### On the phone

On Android 13 and later the app asks once for permission to show notifications. They are used for three things: the playback controls in the notification shade and on the lock screen, the progress of downloads, and the progress of a transcription or translation. Each of these notifications carries a **stop** button. In Android's notification settings the last two appear as the categories **downloads** and **transcription**. The app asks for nothing else and needs no account.

With no subscription yet, the home screen shows:

"no subscriptions yet. + at the top finds a podcast by its name, or takes the address of its feed; sharing a link to this app works too."

Tap **+** at the top to add your first podcast (see "Subscribe to a podcast by its name").

### On the computer

Nothing is asked. The empty window says: "no subscriptions yet. + a feed below finds a podcast by its name, or takes the address of its feed." Click **+ a feed** at the bottom of the left column.

## The screens

This section describes the phone. The computer's window is described under "On the computer".

### Home

The home screen shows one list at a time. The title at the top names the list and ends with **▾**: tap the title to choose between **channels**, **episodes**, **favourites** and **downloaded**. The list being shown carries a ✓.

- **channels**: your subscriptions, the one that published most recently at the top. Under each name: the date of its latest episode and the number of episodes not yet heard. If the last refresh of that channel failed, the reason is shown in place of the date.
- **episodes**: every episode of every channel, newest first.
- **favourites**: the episodes you gave a star.
- **downloaded**: the episodes whose audio is on the phone.

To the right of the title:

- **↻** refreshes all channels.
- **+** opens **add a podcast**.
- **⋯** opens the menu.

Pulling the list down also refreshes: the line reads **pull to refresh**, then **let go to refresh**. While the channels are being fetched, a line counts them: "refreshing: 3 / 12".

A tap on a channel opens it: the title becomes the channel's name, **←** goes back to the channels (so does the phone's back button), **↻** refreshes that channel alone, and pulling down does the same. Inside a channel there is no **+**.

A long press on a channel opens its menu:

- **refresh**: fetches that channel alone.
- **on** or **off**, with **automatic download** written underneath: tap to switch automatic download for that channel.
- **unsubscribe**, with the feed's address underneath.

An episode takes up to two lines for its title, then one line that says, in order: ★ if it is a favourite, the channel (in lists that mix channels), the date, and the one thing worth knowing: **downloading 40 %**, **waiting**, an error, **heard**, "25 min left", **begun**, **on the phone**, or simply its length. Dates are written as words: **today**, **yesterday**, the day of the week within a week, then the date.

A tap on an episode opens it without starting it. A long press opens the episode menu:

- **play**
- **download**, or **stop the download** while it is coming down, or **remove from the phone** (with "the episode stays in the list") once it is there
- **keep as a favourite** or **remove from favourites**
- **mark as heard** or **mark as unheard**
- **share the link**
- **go to the channel** (absent when you are already in that channel)

At the bottom of the home screen, the episode loaded in the player is shown as an inverted row. Tap it to return to the player; long press it for the menu.

### The ⋯ menu of the home screen

- **search**
- **refresh**
- **+ a feed**: opens **add a podcast**
- **import subscriptions**
- **export the subscriptions** (abonnements.opml)
- **black on white** or **white on black**: switches the colours at once
- **settings**

### add a podcast

One field, with the hint **a name, or a feed's address**. If the clipboard holds a web address when you open the screen, it is already in the field, selected, so typing replaces it.

- If the field holds an address, one row appears: **subscribe to this address**. Tap it, or press the keyboard's action key.
- If it holds a few words (two letters at least), the app looks them up in two public directories, Apple Podcasts and fyyd, shortly after you stop typing. It shows **searching the directories…**, then the podcasts found, each with its author or site underneath. Tap one to subscribe. A podcast you already follow reads **already followed**, and a tap opens it instead.

Under the results the app says where they come from: **found in Apple Podcasts and fyyd**, or, when one directory failed, "Apple Podcasts did not answer: these come from the other one" (or the same with fyyd).

After subscribing, the app opens the new channel and shows "subscribed to" followed by its name.

### search

Searches what is already in the app, so it works without a connection. The field's hint is **a channel, an episode**. From two letters on, the screen lists the channels whose name contains what you typed, then the episodes whose title does (the 300 most recent at most). A tap on a channel opens it; a tap on an episode opens the episode; a long press on an episode opens its menu. When you come back from an episode the results are still there.

### The episode screen (the player)

The top bar names the channel. **←** goes back, **☆** / **★** sets or removes the favourite, **⋯** opens the menu.

Below, from top to bottom:

- The whole title, then the date and the length.
- The position as a large clock. To its right the speed, for instance **1×**: each tap moves to the next of 0.8×, 1×, 1.25×, 1.5×, 1.75×, 2×. The speed is kept for all episodes. When the episode has been written down, **the text** appears beside the speed and opens the text screen.
- A thin line showing how far you are. Tap anywhere on it to move there (this also starts the episode if it was not loaded).
- **−5 s**, **▶** (which becomes **❚❚** while playing) and **+10 s**. The two jumps act on the episode that is loaded in the player.
- A chapters row, when the episode's notes contain a list of times and titles: it shows the current chapter and, underneath, "12 chapters". Tap it for the list; the current chapter carries a ✓; tap a chapter to go to its start.
- The episode's notes. Long notes are folded after eight lines: tap **read on…**. In the notes, a tap on a web address opens it; a tap on a time such as 12:34 sends the sound there; a long press on an address copies it; a long press anywhere else copies the whole text.
- A download row: **download** ("it plays over the connection, without being kept"), or the progress with **stop the download**, or **remove from the phone** ("on the phone").
- A text row: see "Write down what is said in an episode" and "Translate the text".

The **⋯** menu holds the same entries as the long-press menu, without **play** and with **stop** at the end. **stop** ends playback, keeps the position, removes the notification and returns to the list.

An episode does not need to be downloaded: **▶** plays it over the connection.

### The sheet before a transcription

When you tap **write down what is said**, a sheet opens with the episode's title and:

- **spoken language**, which reads **to choose** until you pick one. The list of languages opens by itself. It offers the phone's language, English, **let it work it out**, then French, German, Spanish, Portuguese, Russian and Italian, each written in its own language. If another episode of the same channel was written down before, its language comes first, marked **last time**.
- Two qualities: **ordinary** (190 MB, **recommended**) and **careful** (574 MB, **four times slower**). A quality whose model is not on the phone yet reads **to fetch**. **ordinary** is selected to begin with.
- **cancel** and **start**. **start** does nothing until a language is chosen.

### The text screen

Shows what was written down, line by line. The line being spoken is inverted and the list follows the sound, unless you are scrolling. Tap any line to send the sound there (it starts the episode if needed).

At the top: the episode's title, **←** and **⋯**. When a translation exists, two words let you switch: **text** and **translation**. Then **−5 s**, **▶** or **❚❚** with the position, and **+10 s**. The first lines of the episode's notes are shown above the text.

The **⋯** menu:

- **share the text**: sends the text being shown (original or translation) to another app.
- **open the .txt** ("a .txt in Documents/Transcriptions"): opens the saved text file in an app of your choice.
- **write it down again**: returns to the episode and opens the sheet again.

### settings

See "Settings". The last row gives the app's name and version, with: "podcasts, kept on the phone. it goes online only to find and fetch podcasts".

## How to

### Subscribe to a podcast by its name

1. On the home screen, tap **+** (or **⋯**, then **+ a feed**).
2. Type a few words of the podcast's name.
3. Wait for the results and tap the right one.

On the computer: click **+ a feed** at the bottom left, type, and click a result. Pressing Enter starts the search at once.

### Subscribe with a feed's address

1. Copy the address of the podcast's feed.
2. Open **add a podcast**: the address is already in the field. Otherwise paste or type it.
3. Tap **subscribe to this address**.

The address must be that of the feed itself. An address written without "https://" is accepted.

### Subscribe from another app

In a browser or any app, share the feed's link and choose **Add to Reader's Podcasts** in the share sheet. Links of the "feed:" and "podcast:" kind open the app directly.

### Listen to an episode

1. Tap the episode.
2. Tap **▶**.

Or long press the episode and choose **play**. Playback resumes where the episode was left. On the computer: double-click the episode, or select it and press Enter.

### Pause, jump, change speed

In the episode screen use **❚❚**, **−5 s**, **+10 s**, the line, and the speed. The same **−5 s**, play/pause, **+10 s** and **stop** are in the phone's media notification and on the lock screen, where the episode and its channel are named. Headset and Bluetooth buttons work, and playback pauses when headphones are unplugged.

### Go to a chapter or a time

Tap the chapters row and choose a chapter, or tap a time written in the notes.

### Download an episode, or remove it

Open the episode and tap **download**, or long press it and choose **download**. Downloads run one after the other; a notification shows the progress, for instance "downloading 40 % · 2 waiting". An interrupted download carries on from where it stopped when you ask again. To free the space, choose **remove from the phone**: the episode stays in the list with its position. To stop a download, tap **stop the download**, or **stop** in the notification (which stops all those waiting too).

### Have a channel download its new episodes by itself

Long press the channel and tap **off** (above **automatic download**) so that it reads **on**. After each refresh, the episodes that have just appeared are downloaded, three at most per refresh. Episodes already in the list are not fetched. These automatic downloads follow the setting **download on wifi only**.

### Keep an episode as a favourite

Tap **☆** in the episode screen, or long press the episode and choose **keep as a favourite**. Favourites are listed under **favourites**. They stay in the list even when the feed no longer carries them, and **delete when played** spares them.

### Mark an episode as heard or unheard

Long press it and choose **mark as heard** or **mark as unheard**. Either way its position returns to the beginning. An episode you listen to the end is marked **heard** by itself.

### Share an episode

Long press it and choose **share the link**: the title and the address of the audio are handed to the app you pick.

### Refresh

Pull the list down, tap **↻**, or choose **refresh** in the menu. Inside a channel, only that channel is refreshed.

### Unsubscribe

Long press the channel and tap **unsubscribe**. It takes effect at once, without confirmation, and removes the channel's episodes, their downloaded audio and the texts kept in the app.

### Find an episode you already have

**⋯**, then **search**, and type part of a title or of a channel's name.

### Write down what is said in an episode

1. Download the episode. Until then the row reads **write down what is said** with "download the episode first", and a tap starts the download.
2. Tap **write down what is said** ("on the phone; long, and nothing leaves it").
3. Choose the spoken language.
4. Choose **ordinary** or **careful**.
5. Tap **start**.

The first time, the model for the chosen quality is fetched ("fetching the model 30 %"). Then the row shows "writing it down 12 %", followed after a while by an estimate such as "20 min left", then **saving…**. The work goes on with the screen off; a notification shows it. To stop, tap the row (its second line reads **stop**) or **stop** in the notification.

When it is done, **the text** appears in the episode screen and a copy is saved as a .txt file named after the episode in Documents/Transcriptions. Writing the same episode down again replaces that file.

### Read the text while listening

Open the episode and tap **the text**. Tap a line to jump to it.

### Translate the text

Once an episode is written down, the row "translate into" followed by your phone's language appears, unless the episode is already in that language or already translated. Its second line reads "2490 MB · to fetch" the first time, then "on the phone, from the text above". Tap it. The model is fetched if needed, then the row shows "translating 8 %" and an estimate. The translation is made in passages of several sentences. When it is done, open **the text** and tap **translation**.

Translation needs a phone with 8 GB of memory. On a smaller one the row reads "needs a phone of 8 GB; this one has 6" and does nothing.

### Share or open the written text

In the text screen, **⋯**, then **share the text** or **open the .txt**.

### Move subscriptions to or from another podcast app

**⋯**, then **export the subscriptions**: choose where to save abonnements.opml. To bring subscriptions in, **import subscriptions** and pick an OPML file. The app reads each feed ("reading the feeds: 4 / 30") and ends with, for instance, "12 feeds added". Subscriptions you already have are skipped.

### Carry positions and settings between the phone and the computer

1. On the device you listened on, open **settings** (on the computer: **⋯**) and choose **export the settings**. Save reglages.json.
2. Move the file to the other device by any means you like.
3. There, choose **import settings** and pick the file.

The file carries the settings, the list of channels with their automatic download, and, for every episode begun, heard or starred, its position, its state and its star. Channels missing on the receiving side are subscribed to. For each episode, the side that was listened to most recently wins, so importing an older file does not undo what you heard since; a star in the file is always added.

## Settings

Open **⋯**, then **settings**. Each tap on a row moves to its next value.

| Setting | Choices | Default |
|---|---|---|
| **opens on** | **channels**, **episodes**, **favourites**, **downloaded** | **channels** |
| **download on wifi only** | **on**, **off** | **on** |
| **refresh on opening** | **on**, **off** | **on** |
| **delete when played** ("except favourites and transcribed episodes") | **on**, **off** | **off** |
| **colours** | **white on black**, **black on white** | **white on black** |
| **text size** | S, M, L | M |
| **font** | sans-serif, serif, mono | sans-serif |
| **haptic tick** | **on**, **off** | **on** |

- **opens on**: changing it switches the home screen to that list at once. After that, the app comes back to whichever list you were last looking at.
- **download on wifi only**: concerns the automatic downloads. A download you ask for yourself always starts, whatever the connection. The models for transcription and translation are also fetched whatever the connection.
- **refresh on opening**: when the app is opened, all channels are refreshed, at most once an hour.
- **delete when played**: when an episode is heard to the end, or marked as heard, its downloaded audio is removed. Favourites and episodes that were written down keep theirs.
- **haptic tick**: a short vibration on the player's controls.

Between these rows the screen offers the two exchange files, introduced by: "the two files that carry everything: the subscriptions as opml, which any podcast app reads, and the settings with where each episode was left." The rows are **export the subscriptions** (abonnements.opml), **import subscriptions**, **export the settings** (reglages.json) and **import settings**.

Two things are set elsewhere: the speed, in the episode screen (1× to begin with), and **automatic download**, per channel, in the channel's long-press menu (off to begin with).

## Your data

Everything is kept on the phone: the subscriptions, the list of episodes with positions and stars, the downloaded audio, the texts and translations, and the models. Only the .txt copy of a text is placed where other apps can see it, in Documents/Transcriptions.

The position of the episode playing is saved every few seconds.

The app uses the network for these things only:

- fetching the feeds you subscribed to, from their own servers;
- playing or downloading the audio, from the servers the feed names;
- looking up a name in **add a podcast**: the words you type go to Apple Podcasts and to fyyd, and your phone's country goes to Apple so that it answers with that country's podcasts first;
- fetching the transcription and translation models, once, from Hugging Face.

The audio and the text of an episode never leave the phone: writing down and translating are done on it.

For each channel the app keeps the 50 most recent episodes of the feed. Older ones leave the list, except those that are downloaded, begun, starred or written down.

There is no automatic synchronisation and therefore no conflict to resolve: the two files described under "Carry positions and settings between the phone and the computer" are the only exchange. Downloaded audio, texts and translations are not carried by these files. Text size, **haptic tick** and **download on wifi only** exist on the phone only and are not taken over by the computer.

Uninstalling the app removes everything it kept, including downloaded episodes and models. The .txt files in Documents/Transcriptions stay. Export the two files first if you want to find your subscriptions and positions again.

## With the other apps

- **Home-screen widget**: **Reader's Podcasts · last played** ("the last episode played, and a button to carry on"). One row, four cells wide, resizable in width. It shows the title of the last episode played and its position and length; **▶** resumes it and **❚❚** pauses, without opening the app; a tap on the title opens the episode. Before anything has been played it reads **nothing played yet**. It follows the app's colours.
- **Share sheet**: **Add to Reader's Podcasts** takes a feed's address shared from any app.
- **Links**: links of the "feed:" and "podcast:" kind open the app and subscribe.
- **Shared models**: the transcription and translation models are shared with Reader's Audio Player and Reader's Recorder. If one of them already holds a model, Reader's Podcasts uses it instead of fetching it again, and the other way round.
- **The written text**: the .txt in Documents/Transcriptions opens in any app that reads text, a book reader for instance.

## On the computer

The computer program is one window in the same two colours. It has no transcription, no translation and no widget. It adds YouTube.

### The window

- **Left column**: **episodes**, **favourites**, **downloaded**, each with its count, then your channels, the one that published most recently first, each with its number of unheard episodes. There is no **channels** row: the column is the list of channels. A channel whose last refresh failed says why when the pointer rests on it ("last refresh failed: …"). At the bottom: **+ a feed**.
- **Middle**: the name of the list, **⋯**, and the episodes. A click selects an episode; a double click, or Enter, plays it; a right click opens its menu.
- **Right**: the selected episode: title, channel, date, length; three actions, **listen** (or **pause**), **download** (or **stop the download**, or **remove from this computer**) and **keep as a favourite** (or **remove from favourites**); the **chapters**, each a link that sends the sound there; and the notes, where web addresses open in the browser and times send the sound there.
- **Bottom**: the position, the title with its length and channel (or **nothing playing**), the line (click to move), **−5 s**, **▶** / **❚❚**, **+10 s**, and the speed, for instance "1× speed" (click for the next of 0.8, 1, 1.25, 1.5, 1.75, 2).

Messages appear for a few seconds in the bar at the very bottom of the window.

### Menus

**⋯**: **search**, **refresh**, **+ a feed**, **import subscriptions**, **export the subscriptions**, **import settings**, **export the settings**, **black on white** or **white on black**, **settings**.

Right click on an episode: **play**, **download** / **stop the download** / **remove from this computer**, **keep as a favourite** / **remove from favourites**, **mark as heard** / **mark as unheard**, **copy the link**, **open the channel**.

Right click on a channel: **refresh**, **automatic download** (ticked when on), **unsubscribe**.

**search** shows a field above the episodes and keeps, in the list being shown, the episodes whose title contains what you type. Escape closes it.

### What differs from the phone

- **YouTube**: paste the address of a channel (an "@name" address, a "/channel/…" address) or of a playlist in **add a podcast**; it becomes a channel like any other. To listen to a video, the program first fetches its audio with yt-dlp, a separate tool that must be installed on the computer ("the audio is fetched first; it will play by itself"). Without it: "YouTube needs yt-dlp, which is not installed".
- **automatic download**: after each refresh, the three most recent episodes of the channel are downloaded if they are unheard and not yet on the computer.
- **refresh on opening** refreshes at every start.
- **delete once heard** spares favourites and YouTube videos.
- There is no **stop**: pause, or let the episode end. The position is also saved when the window is closed.
- The window reopens on the list it was showing when it was closed.
- There is no **download on wifi only**, no **haptic tick**, and the text size is a number instead of S, M, L.
- **unsubscribe** takes effect at once, as on the phone, and removes the channel's downloaded audio.

### Settings on the computer

**⋯**, then **settings**; confirm with **ok**.

| Setting | Choices | Default |
|---|---|---|
| **colours** | **white on black**, **black on white** | **white on black** |
| **font** | **sans-serif**, **serif**, **mono** | **sans-serif** |
| **text size** | 9 to 24 | 12 |
| **opens on** | **episodes**, **favourites**, **downloaded** | **episodes** |
| **refresh on opening** | ticked or not | ticked |
| **delete once heard** | ticked or not | not ticked |

**opens on** is stored and written into the exported settings file; the window itself reopens on the last list shown.

### Keyboard and command line

- Enter plays the selected episode; in **add a podcast**, Enter subscribes to an address or starts the search.
- Escape closes the search field.
- Started with a feed's address as its argument, the program subscribes to it: `readers-podcasts https://example.org/feed.xml`. Installed from the package, it is also offered by the system for "feed:", "podcast:" and "pcast:" links.

### Where its files live

- Subscriptions, episodes and downloaded audio: `~/.local/share/readers-podcasts` (audio in its `audio` folder).
- Settings: `~/.config/readers-podcasts/config.json`.

Export proposes `abonnements.opml` and `reglages.json` in your home folder.

Playing sound needs the system's Qt multimedia package; without it the program still opens and says "audio is missing: install python3-pyqt5.qtmultimedia".

## Limits

- One episode plays at a time; there is no queue and no "next episode".
- No sleep timer, no artwork, no video.
- The address you give must be the feed itself; the app does not look for a feed inside a web page.
- The Android app refuses YouTube addresses.
- Transcription works on a downloaded episode only, and is slow: count on a long wait for a long episode, four times longer with **careful**.
- Translation needs a phone with 8 GB of memory and a model of 2490 MB; it translates into the phone's language only.
- Chapters are read from the notes: the list is recognised only when it has at least two lines with a time and a title, in order.
- A channel's list holds its 50 most recent episodes, plus those you downloaded, began, starred or wrote down.
- Episode notes are kept up to 10 000 characters.
- No automatic synchronisation between devices.
- On the computer: no transcription, no translation, and **search** looks at episode titles in the current list only.

## Messages and problems

### Subscribing and refreshing

- **reading the feed…**, "reading the feeds: 4 / 30", "refreshing: 3 / 12": work in progress. On the computer: **refreshing…**.
- "that feed could not be read." followed by a reason: the address is not a feed, or the server did not answer. Check the address.
- **YouTube channels are not supported.** (phone): the address is a YouTube one.
- "no channel was found at that address" (computer): the YouTube address does not lead to a channel.
- **no connection**: the server could not be reached.
- "the server answered with an error (HTTP 404)": the feed or the file is no longer at that address (the number varies).
- "not refreshed: …", under a channel's name: the last refresh of that channel failed; the rest is the technical reason. On the computer the same information is in the tooltip, "last refresh failed: …".
- **no subscription in that file**: the file chosen holds no feed. On the computer the same message appears when every feed in the file is already followed.
- **that file could not be read**, **could not write the file**: the import or export did not go through; pick another file or another place.
- **subscriptions exported**, **settings exported**, **settings imported**, "12 feeds added": done.
- "the refresh failed. …", "the import failed. …" (computer): followed by the technical reason.

### Finding a podcast

- **no podcast of that name in the directories**: try other words, or paste the feed's address.
- **the directories do not answer — is the phone online?** (on the computer: "is the computer online?"): neither directory could be reached.
- "fyyd did not answer: these come from the other one": only one directory answered; the results may be incomplete.
- **nothing of that name here** (in **search**): nothing you follow matches.

### Downloading and playing

- **waiting**: the download is queued behind another.
- **waiting for wifi**: an automatic download was not made because the phone was not on wifi. Download the episode yourself, or switch **download on wifi only** off.
- **download cut short — try again to carry on**: the connection dropped; ask again and it resumes.
- "download failed: …" (computer: "the download failed. …"): followed by the reason. The full text is shown in the episode screen.
- **that episode could not be played**: the audio could not be read, often because there is no connection for an episode that is not downloaded.
- **nothing on the phone yet. a downloaded episode plays without a connection.**: the **downloaded** list is empty. On the computer: **nothing on this computer yet.**
- **no favourite yet. a long press on an episode keeps it here.**: the **favourites** list is empty. On the computer: **no favourite yet.**
- **nothing here yet. ⋯ refreshes.**: the list is empty; refresh. On the computer: **nothing here yet.**
- **copied**: the address or the text of the notes is in the clipboard.

### Writing down and translating

- **download the episode first**: the episode's audio must be on the phone.
- "fetching the model 30 %": the model is being fetched; this happens once per quality.
- **the model is not on the phone**: the model could not be opened; start again so that it is fetched.
- "download refused (HTTP 403)": the model's server refused; try later.
- "not enough space: 2600 MB needed": free that much storage and start again.
- **no sound in this file**: the downloaded file holds no audio the app can read.
- "could not write it down: …", "the translation failed: …": followed by the technical reason.
- "could not create" followed by a file name: the .txt could not be saved in Documents/Transcriptions.
- "needs a phone of 8 GB; this one has 6": this phone cannot translate.
- **that .txt is no longer where it was**: the file was moved or deleted; **write it down again** creates it anew.
- **nothing written down yet.**: the text screen has no text for this episode.


# Reader's Audio Player

*Android 1.6.1*

## What it is

Reader's Audio Player plays the audio files that are on your phone and resumes each one where you left it. It can also write down what is said in a file (a transcription), write the main points of that text, and translate it into the language of your phone. All three are done on the phone itself: the audio and the text are never sent anywhere.

The app is black and white, text only, and follows the language of the phone: English, French, German, Spanish, Portuguese or Russian.

It deliberately does not manage a music library: there are no albums, no playlists, no previous or next track. One file plays at a time. It has no account and asks for no access to your storage; it only knows the files you open with it.

## First start

### What the app asks

On Android 13 and later, the app asks once for permission to show notifications. Notifications carry the playback controls (also shown on the lock screen) and the progress of a transcription, with a button to stop it.

Nothing else is asked: no account, no server, no storage permission. The app reaches the internet only to download the models it needs for transcription, main points and translation, the first time each is used.

### The empty screen

The first screen is titled **audio**. While the list is empty it shows:

> nothing here yet. + below opens audio files from the phone; “open with” from any app works too.

At the bottom, **+ open audio files** opens the phone's file picker.

## The screens

### The list (audio)

The list shows every file you have opened, the last one played first. Files never played come after, the most recently added first.

Each line shows the title of the file (its name without the extension) and, underneath, a status line:

- where you stopped and the total length, for example `12:34 / 45:00`, or the length alone if the file has not been started;
- then, if it applies: **transcript** when a transcription exists, the progress of the work under way (for example **transcribing · 42%**), **waiting to transcribe** when the file is queued, or an error message if the last attempt failed.

What you can do:

- **Tap a line**: the file starts playing where it was left and the player opens. If the file is already the one loaded in the player, the player simply opens.
- **Long press on a line**: opens the file's menu (see below).
- **The inverted line at the bottom** (white on black becomes black on white): the file currently loaded, preceded by **▶** when paused or **❚❚** when playing. Tap it to return to the player.
- **+ open audio files**: opens the phone's file picker, limited to audio files. You can pick several at once.
- **⋯** at the top right: a small menu with **+ open audio files**, then **black on white** or **white on black** (switches the colours at once) and **settings**.

### The file's menu

It opens by a long press in the list, or with **⋯** in the player. The title of the file is at the top. The entries depend on the state of the file:

| Entry | What it does | Shown when |
|---|---|---|
| **play** | Starts the file and opens the player. | From the list only. |
| **open the transcript** (*a .txt in Documents/Transcriptions*) | Opens the transcription in an app that reads text; the phone lets you choose which. | A transcription exists. |
| **transcribe** | Opens the transcription sheet. | No transcription yet, nothing in progress. |
| **transcribe again** | Opens the transcription sheet; the new text replaces the old one. | A transcription exists, nothing in progress. |
| **stop the transcription**, **stop the summary** or **stop the translation** | Stops the work in progress. | The file is being worked on or is waiting. |
| **share the audio…** | Sends the audio file to another app. | Always. |
| **share the transcript…** | Sends the transcription to another app. | A transcription exists. |
| **the main points (beta)** | Reads the main points, writes them, or fetches the model that writes them (see the player below). | A transcription exists, nothing in progress. |
| **translate into …** or **open the translation (…)** | Translates the transcription into the language of the phone, or opens the translation already made. | A transcription exists, nothing in progress, and a translation would change something. |
| **save a copy to a folder…** | Copies the audio file to a folder you choose. | Always. |
| **stop** | Stops playback, removes the playback notification and returns to the list. The position is kept. | From the player only. |
| **remove from the list** | Takes the file out of the list. | From the list only. |

Tap outside the menu, or use the back button, to close it.

### The player

The title of the file is at the top; tap it (or the arrow **←**) to go back to the list. **⋯** opens the file's menu.

From top to bottom:

- **The position**, in large figures, and under it the total length.
- **The progress line**: tap anywhere on it to jump to that point of the file.
- Three buttons: **−5 s** goes back five seconds, **▶** plays and **❚❚** pauses (the button is inverted while the file plays), **+10 s** skips ten seconds ahead.
  If the file shown is not loaded (for example after **stop**, when the player is opened from the widget), **▶** starts it, a tap on the progress line starts it at that point, and **−5 s** and **+10 s** do nothing until it plays.
- **speed**: shows the current speed, for example **1×**. Each tap moves to the next one: 0.8×, 1×, 1.25×, 1.5×, 1.75×, 2×, then back to 0.8×. The speed applies to every file.

Below the rule comes the transcription part, which changes with the state of the file:

- No transcription yet: **transcribe** (*choose the language and the quality*). Tap it to open the transcription sheet.
- Work in progress: one line showing the step and its progress — **fetching the model · 12%**, **transcribing · 42%**, **writing the main points, 30%**, **translating · 55%**, **saving the transcript** — with **stop the transcription**, **stop the summary** or **stop the translation** underneath. Tap the line to stop.
- File in the queue: **waiting to transcribe**, with the same stop line underneath. Tap to stop.
- A transcription exists:
  - **open the transcript** (*a .txt in Documents/Transcriptions*);
  - **share the transcript…**;
  - **the main points (beta)**, with a second line that says where things stand (see "Get the main points of a transcription");
  - **translate into …** or **open the translation (…)**, when it applies.

If the last attempt failed, the reason is written under these lines.

### The transcription sheet

It opens from **transcribe** or **transcribe again**, and is shown before every transcription. It has the title of the file at the top, then:

- **language spoken**: the language of the audio. It starts on the language of your phone. Tap it to choose among the phone's language, English, **detected** (the app works out the language by itself), French, German, Spanish, Portuguese, Russian and Italian. A **✓** marks the current choice.
- **ordinary** — *190 MB · recommended*: the quick model. It is the one selected when the sheet opens.
- **careful** — *574 MB · four times slower*: a more accurate model, with better punctuation, but much slower.
  The selected quality is the inverted line. A model that is not yet on the phone is marked **to fetch**; it is downloaded when the transcription starts.
- **main points too (beta)**: when this line is inverted, the main points are written right after the transcription. Its second line shows the size of the model (2105 MB) and **to fetch** if it is not on the phone, or **shared with …** when another Reader's app already holds it. If the model is not on the phone, a first tap downloads it (you can watch the progress on the line); tap again to switch the line on. On a phone with too little memory the line reads **this phone has … GB: not enough** and cannot be switched on.
- **cancel** closes the sheet; **transcribe** starts the work.

### The main points (beta)

This screen opens when you tap **the main points (beta)** on a file whose points are written (*written · tap to read them*). It shows the title of the file, then the text: two sentences on what the recording is about, then the points, one per line.

At the bottom:

- **open the transcript** (*a .txt in Documents/Transcriptions*): opens the full text file.
- **write them again**: asks for the **language spoken** — in fact the language the points will be written in — then writes them anew. The list is the same as in the transcription sheet, without **detected**. If the model is no longer on the phone, the line says so and a tap fetches it.

### Settings

Reached with **⋯** in the list, then **settings**. See the "Settings" section.

### The notifications

While a file plays, a media notification shows its title with **−5 s**, play or pause, **+10 s** and **stop**. The same controls are on the lock screen, and the buttons of a headset or a Bluetooth device work. Tapping the notification opens the player.

While the app transcribes, writes the main points, translates or downloads a model, a second notification shows the title of the file, the step and its progress, with a **stop** button. Tapping it opens the app.

## How to

### Open audio files

1. In the list, tap **+ open audio files**.
2. In the phone's file picker, choose one file, or several.
3. If you chose a single file, it starts playing and the player opens. If you chose several, they are added to the list.

A file opened this way stays where it is on the phone; the app only remembers where to find it.

### Open a file from another app

In a file manager or any other app, choose "open with" or "share" on an audio file and pick **Reader's Audio Player**. The file is added to the list, starts playing, and the player opens.

When the other app only lends the file for the moment, which is the usual case here, Reader's Audio Player keeps its own copy so that the file still plays later.

### Play, pause and resume

1. Tap a file in the list. It starts where you left it.
2. In the player, tap **❚❚** to pause and **▶** to resume.

The position is saved every few seconds while the file plays, and when you pause or stop. A file left within three seconds of its end starts again from the beginning; so does a file that played to the end. Playback pauses by itself when headphones are unplugged.

### Move within a file

- Tap **−5 s** or **+10 s**.
- Or tap the progress line at the place you want to reach.

### Change the speed

In the player, tap the **speed** line until the speed you want is shown: 0.8×, 1×, 1.25×, 1.5×, 1.75× or 2×.

### Stop playback

In the player, tap **⋯**, then **stop**. You can also use **stop** in the playback notification. The position is kept.

### Transcribe a file

1. Open the file in the player and tap **transcribe** (or long press the file in the list, then **transcribe**).
2. Check **language spoken**. Tap it to change it, or choose **detected** if you do not know.
3. Choose the quality: **ordinary** (recommended for long recordings) or **careful** (four times slower).
4. If you also want the main points, tap **main points too (beta)** so that the line is inverted (the first tap downloads the model if it is not on the phone).
5. Tap **transcribe**.

The first time, the model is downloaded (**fetching the model · …%**); then the progress reads **transcribing · …%**. You can leave the app: the work continues, and the notification shows where it is. When it is finished, the file shows **transcript** in the list and the player offers **open the transcript**.

You can start several files: they are done one after the other, and the ones waiting show **waiting to transcribe**.

### Stop a transcription, a summary or a translation

In the player, tap the line that shows the step under way, or choose **stop the transcription**, **stop the summary** or **stop the translation** in the file's menu, or tap **stop** in the notification. This stops the work in progress and also empties the queue: the files that were waiting are not processed.

### Read or share a transcription

- **open the transcript** opens the text in the app of your choice (any app that reads text files, Reader's Books for example).
- **share the transcript…** sends the text file to another app. When the text is short (under about 100,000 characters) it is also sent as plain text, so that note and messaging apps accept it.

### Get the main points of a transcription

There are two ways.

**With the transcription.** In the transcription sheet, switch on **main points too (beta)** before tapping **transcribe**. The choice is remembered for the next time.

**Afterwards, from a transcription already made.** In the player, look at the second line under **the main points (beta)**:

1. *2105 MB · to fetch*: tap to download the model. The line shows **fetching the model · …%**. If the download was interrupted, it reads **…% downloaded · tap to continue**: tap to carry on from there.
2. *written at the top of the transcript*: the model is on the phone. Tap to write the points; progress reads **writing the main points, …%**.
3. *written · tap to read them*: the points are ready. Tap to read them.

The points are written in the language chosen for the transcription; with **detected**, in the language of the phone. The instructions exist in English, French, German, Spanish, Portuguese and Russian; for any other language the points come out in English. To have them in another language, open them and use **write them again**.

The result is two sentences on the subject, then a short list of points. They are also placed at the top of the transcription's text file, under the heading **MAIN POINTS**, above the full text.

This function is marked beta: it is written by a small model, on the phone, and can miss things.

### Translate a transcription

1. Make sure the file has a transcription.
2. In the player (or in the file's menu), tap **translate into …**. The language offered is the language of your phone if it is English, French, German, Spanish, Portuguese or Russian; otherwise English.
3. The first time, the model is downloaded (2490 MB); the second line reads *2490 MB · to fetch* until then. Progress then reads **translating · …%**.
4. When it is done, the line becomes **open the translation (…)**. Tap it to read the translation.

The translation is a second text file, next to the transcription, named with the title followed by the language code in brackets, for example `title (en).txt`. Only the text of the transcription is translated, not the main points.

The line is not offered when the transcription was made in that same language. On a phone with too little memory it reads **needs a phone of 8 GB; this one has …** and does nothing.

### Share the audio file

In the file's menu, tap **share the audio…** and pick the app to send it to.

### Save a copy of the audio file

1. In the file's menu, tap **save a copy to a folder…**.
2. Choose the folder in the phone's file picker; the name of the file is proposed, and you can change it.
3. The app shows **copied**, or **could not copy the file** if it failed.

### Remove a file from the list

Long press the file in the list, then tap **remove from the list**. If it was playing, playback stops. The original audio file is not deleted, and neither are the text files in Documents/Transcriptions. The app's own copy of the file, if it had made one, is deleted, together with what the app kept about the file.

### Switch between white on black and black on white

In the list, tap **⋯**, then **black on white** or **white on black**. The same choice is in **settings**, on the **colours** line.

### Put the resume widget on the home screen

Add the widget named **Reader's Audio Player · last played** from your home screen's widget list. See "With the other apps".

## Settings

The screen opens with a reminder: *transcripts are plain .txt files in Documents/Transcriptions; any text or e-book app opens them.* Each setting changes with a tap on its line.

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **colours** | The colours of the app and of its widget. | **white on black**, **black on white** | **white on black** |
| **text size** | The size of the text in the whole app. | S, M, L | M |
| **font** | The typeface. | sans-serif, serif, mono | sans-serif |
| **haptic tick** | A short vibration when you tap **−5 s**, **▶** / **❚❚** or **+10 s** in the player. | **on**, **off** | **on** |

The last line, **Reader's Audio Player**, only describes the app: *plays audio files and transcribes them on the phone; nothing leaves it*.

Other choices are made where they are used and are remembered:

| Choice | Where | Default |
|---|---|---|
| **speed** | In the player; applies to every file. | 1× |
| **main points too (beta)** | In the transcription sheet. | Off. It is switched on once the model has been downloaded. |

The language spoken and the quality are asked again before every transcription: the sheet always opens on the language of the phone and on **ordinary**.

## Your data

### Where things are

- **The audio files** stay where they are on the phone. The exception is a file received through "open with" or "share" from another app, which the app copies into its own private space.
- **The list**, the position in each file and the settings are kept in the app's private space, on the phone only.
- **The transcriptions** are plain text files in the phone's **Documents/Transcriptions** folder, named after the title of the file (`title.txt`). A new transcription of the same file replaces the previous one. When main points have been written, they are at the top of that same file. A translation is a second file beside it (`title (en).txt`).
- The app also keeps its own copy of each transcription, of its main points and of its translation. If the translation's text file has been deleted or moved, **open the translation (…)** writes it out again.
- **The models** (190 MB, 574 MB, 2105 MB and 2490 MB) are in the app's private space.

### What goes over the network

Only the downloads of the models, from the Hugging Face website (huggingface.co), the first time each is needed. Nothing is uploaded: neither the audio, nor the transcriptions, nor the list. There is no account, no synchronisation and no statistics.

A download that was cut is resumed from where it stopped at the next attempt.

### Shared models

The models are shared with Reader's Recorder, Reader's Podcasts and Reader's Notes when they carry the same signature, which is the case for the published versions: a model downloaded by one of them is used by the others without being downloaded again. In the transcription sheet, the main-points line then reads **shared with …**.

### Export, backup, uninstalling

There is no export or import of the list. To keep a transcription elsewhere, use **share the transcript…** or copy the files from Documents/Transcriptions; to keep an audio file elsewhere, use **save a copy to a folder…**.

Uninstalling the app removes the list, the positions, the settings, the copies of audio files the app had made, its own copies of the texts and the downloaded models. The text files in Documents/Transcriptions and your original audio files are not removed.

## With the other apps

### Home-screen widget

The app offers one widget, **Reader's Audio Player · last played** (*the last file played: ▶ resumes it where you stopped*). It is one row high and four cells wide, and can be made wider or narrower.

- It shows the title of the last file played and, under it, the position and the length.
- **▶** resumes the file where you stopped, without opening the app; **❚❚** pauses it. While the file plays, the time runs on the right and the length is shown under the title.
- Tap the title to open the player.
- Before anything has been played it reads **nothing played yet**.

The widget uses the colours chosen in the app.

### Opening and sharing

- Reader's Audio Player appears in "open with" and in "share" for audio files in other apps.
- Transcriptions and translations are ordinary text files: any app that reads text opens them, Reader's Books among them.
- **share the audio…** and **share the transcript…** send to any app that accepts them.

## Limits

- One file plays at a time; there is no playlist, no queue of files to play, no previous or next.
- No folders, no search, no sorting other than "last played first"; a file cannot be renamed in the app.
- The speed goes from 0.8× to 2× in six steps; there is no sleep timer and no bookmark.
- The app opens only audio files, and plays the formats the phone itself can read.
- The main points need a phone with about 6 GB of memory; the translation needs a phone of 8 GB. Each needs its model, and room to download it: about 2.2 GB and 2.6 GB of free storage.
- Main points are not written for a very short text (under about 120 words).
- The translation goes only towards the language of the phone (English, French, German, Spanish, Portuguese, Russian; English for any other phone language). You cannot choose another target language.
- Once a translation exists, the app offers to open it, not to make it again.
- A passage that could not be translated is left in the original language in the translation.
- The careful quality is about four times slower than the ordinary one; a long recording can take a long time.
- Stopping a job also cancels all the jobs that were waiting.

## Messages and problems

| Message | What it means, what to do |
|---|---|
| **this file cannot be opened — open it again with +** | The file could not be read: it was moved, deleted, or is not in a format the phone can play. Open it again with **+ open audio files**. |
| **the transcript file is no longer there** | The text file in Documents/Transcriptions was deleted or moved. The file goes back to offering **transcribe**. |
| **(no speech detected)** | Written in the transcription when no speech was found in the audio. |
| **no connection** | A model could not be downloaded because the internet could not be reached. Connect and try again. |
| **download refused (HTTP …)** | The server refused the download. Try again later. |
| **download cut short — try again to carry on** | The download stopped before the end. Start again: it continues from where it stopped. |
| **download failed: …** | Another download error; the text that follows comes from the phone. Try again. |
| **…% downloaded · tap to continue** | A download of the main-points model was interrupted. Tap to resume it. |
| **not enough space: … MB needed** | The phone lacks storage for the model. Free the amount shown and try again. |
| **the model is missing — try again to fetch it** | The transcription model could not be found after its download. Start the transcription again. |
| **no sound in this file** | The file contains no audio track that can be transcribed. |
| **transcription failed: …** | The transcription stopped on an error; the text that follows comes from the phone. Try again. |
| **could not create …** | The text file could not be created in Documents/Transcriptions. |
| **the main points could not be written** (possibly followed by a reason) | The model returned nothing usable, the text is too short, or the phone had too little free memory at that moment. Close other apps and try again. The transcription itself is not affected. |
| **this phone has … GB: not enough** | The phone does not have the memory needed to write main points. The function is not available on it. |
| **needs a phone of 8 GB; this one has …** | The phone does not have the memory needed to translate. The function is not available on it. |
| **the translation failed** (possibly followed by a reason) | The translation could not be made. Try again. |
| **could not copy the file** | **save a copy to a folder…** failed. Check the folder chosen and the free space. |
| **waiting to transcribe** | Another file is being worked on; this one comes next. |
| **nothing played yet** | Shown by the widget while no file has been played. |

If main points were asked together with a transcription and do not appear, the transcription is kept all the same: the points are attempted after the text has been saved, and a failure at that step is not reported. Ask for them again from **the main points (beta)** in the player.


# Reader's Mindful Tool

*Android 1.0.2*

## What it is

Reader's Mindful Tool is a meditation bowl with three uses: one strike every X minutes until you stop it, a sitting of X minutes closed by three bowls, and bowls at set times every day. It is black and white and made of text only, like the other Reader's apps. Every bowl is set as an alarm-clock alarm and played on the phone's alarm channel, so it sounds on time through silent mode, Do Not Disturb and hours of sleep with the screen off. It has no guidance, no statistics, no streaks and no account, and it cannot use the network at all.

The app exists in English, French, German, Spanish, Portuguese and Russian. It follows the language of the phone; there is no language setting inside the app.

## First start

On Android 13 and later, the app asks once for permission to show notifications. The only notification it ever shows is the silent one displayed while a session runs, which carries the buttons **stop the bowls** and **stop meditating**. If you refuse, you stop a session from the app or from the widget instead.

There is no account, no server and nothing to fill in. The first screen, titled **mindful**, already works:

- **a bowl every** 10 min, with the line **one strike, again and again, until you stop it**;
- **meditate** 20 min, with the line **silence, then three bowls at the end**;
- **bowls at set times**, with the line **none yet — tap to add a time of day**;
- the current bowl, **Tibetan bowl (E♭)**, with the word **bowl** under it.

The app starts white on black.

One thing is worth doing on the first day: open **settings** and tap **allow running in the background** (see "Let the app run in the background" below). The app does not ask for it by itself.

## The screens

### Home (mindful)

The home screen has four lines, separated by thin rules.

**a bowl every N min.** The number of minutes is underlined: tap the words to change it (see "The minutes prompt"). Tap **▶** at the end of the line to start. The first bowl sounds N minutes after the start, not at the start. While it runs, **▶** becomes **■** on a filled square, the minutes are no longer underlined and cannot be changed, and the line under the title reads **next at 14:30 · in 04:12**, followed by **· 3 rung** once at least one bowl has sounded. Tap **■** to stop.

**meditate N min.** Same controls. Nothing sounds at the start. While it runs, the line under the title reads **until 14:50 · 12:40 left** and a thin line below fills from left to right as the sitting goes on. At the end three bowls sound and the line returns to **▶**. Tap **■** to stop early; no bowl sounds then.

The time left is shown as minutes and seconds, or hours, minutes and seconds beyond one hour.

The two functions are independent: you can run both at the same time.

**bowls at set times.** The line under it lists the times that are switched on, for example **07:00 ×3  12:30** (×3 marks a time that rings three bowls). Tap the line to open the screen "bowls at set times".

**The bowl.** The last line shows the name of the bowl in use, with **bowl** under it. Tap it to open the settings, where the bowl is chosen.

**⋯** at the top right opens the menu:

| Entry | What it does |
|---|---|
| **bowls at set times** | Opens the screen of the daily times. |
| **hear the bowl** | Plays one strike of the bowl in use. |
| **black on white** / **white on black** | Switches to the other colours; the entry names the colours you will get. |
| **settings** | Opens the settings. |

Tap outside the menu, or press the phone's back button, to close it without choosing.

### The minutes prompt

Tapping the words of **a bowl every** opens a small panel titled **every how many minutes?**; tapping the words of **meditate** opens **how many minutes?**. The current number is already in the field. Type a whole number from 1 to 240 and tap **ok** (or the confirm key of the keyboard). **cancel**, a tap outside the panel or the back button close it without changing anything.

If what you typed is not a number from 1 to 240, the panel stays open and its title shows **(1–240)**.

### bowls at set times

This screen lists the bowls that ring every day at a fixed time. At the top: **Every day at these times, one strike or three. Tap a time to change it.** When the list is empty it shows **no time set yet**.

Each line shows the time and **one bowl** or **three bowls**, with **on** or **off** under it. Times that are on are shown in inverted colours. The list is sorted by time of day.

Tap a line to open its menu, titled with the time:

| Entry | What it does |
|---|---|
| **turn off** / **turn on** | Stops this time from ringing without deleting it, or switches it back on. |
| **one bowl** / **three bowls** | Changes the number of bowls; the entry names what you will get. |
| **change the time** | Opens the time prompt with the current time. |
| **delete** | Removes the time at once, without asking for confirmation. |

**+ new time** at the bottom opens a panel titled **time (hh:mm)**. Type the time on the 24-hour clock and tap **ok**. You may type **7:30**, **07:30**, **7h30**, **7.30**, **0730**, or just **7** for 07:00. A new time is switched on and rings three bowls. If the time is not understood, the panel stays open and its title shows **(hh:mm)**.

Tap the title line with the arrow **←**, or press back, to return to the home screen.

### settings

From top to bottom:

- The line **The bowl for every sound in the app. Tap one to hear it.**, then the five bowls: **Tibetan bowl (E♭)**, **singing bowl**, **gong bowl**, **Satipanya**, **enpleineconscience.ch**. The one in use is shown in inverted colours. Tapping a bowl chooses it and plays one strike.
- **your own sound…**, with the line **an mp3 or wav file from the phone, in place of the single strike; three bowls = played three times**. Tapping it opens the phone's file picker. Once a file has been chosen, this line shows the file's name with **your own recording; three bowls = played three times**, and tapping it opens a menu with **use this sound** and **pick another file…**.
- **allow running in the background**, with the line **so the bowl always sounds on time, even after hours of deep sleep**. Once allowed, it reads **runs in the background: allowed** and tapping it does nothing.
- **colours**, **text size**, **font**, **haptic tick**: each line shows the current choice above the name of the setting; tap to move to the next choice (see "Settings").
- **Reader's Mindful Tool**, with **a bowl every X minutes, a timed sit, bowls at set times**, and **Pierre Gallaz · developed with Claude Code**: information only.

### The notification

While a session runs, or while a bowl is sounding, the phone shows one silent notification in the category **running session**. Its text is:

- **a bowl every 10 min · next at 14:30** while the repeated bowl runs;
- **meditating 20 min · until 14:50** while a sitting runs, with a progress bar and a countdown;
- both lines when both run;
- **the bowl** while a bowl sounds with no session running (a bowl at a set time, or one you asked to hear).

It carries the buttons **stop the bowls** and **stop meditating**, each shown only when that function runs. Tapping the notification opens the app. It disappears when nothing runs any more and the sound has finished.

### The widget's set-up screen

When you place the widget on a home screen, a screen titled **Reader's Mindful Tool** asks **What should this widget show? Both functions stacked, or just one.** and offers **both**, **a bowl every X minutes only** and **meditation period only**. Tapping the title line with **←** cancels and the widget is not placed.

## How to

### Ring a bowl every X minutes

1. On the home screen, tap the words **a bowl every** and type the number of minutes (1 to 240), then **ok**.
2. Tap **▶** on that line.
3. Put the phone down; the screen can go off. One strike sounds every X minutes, counted from the moment you started.
4. To stop, tap **■** on the line, or **stop the bowls** in the notification.

The bowls go on with no end until you stop them.

### Meditate for X minutes

1. Tap the words **meditate** and type the length in minutes (1 to 240), then **ok**.
2. Tap **▶** on that line. Nothing sounds at the start.
3. At the end, three bowls sound and the sitting ends by itself.
4. To stop early, tap **■**, or **stop meditating** in the notification.

### Have a bowl partway through a sitting

Start both functions. For example **meditate** 30 min and **a bowl every** 10 min, started one after the other, give a strike at about 10 and 20 minutes and three bowls at the end. The repeated bowl is not stopped by the end of the sitting: tap its **■** afterwards.

### Ring a bowl at the same time every day

1. Tap **bowls at set times** on the home screen (or in the **⋯** menu).
2. Tap **+ new time**, type the time, tap **ok**.
3. The time rings three bowls. For a single strike, tap the time and choose **one bowl**.

These bowls ring every day whether the app is open or not, and whether a session runs or not.

### Pause, change or remove a daily time

1. Open **bowls at set times** and tap the time.
2. Choose **turn off** to keep it without ringing (and **turn on** to bring it back), **change the time** to type another time, or **delete** to remove it.

### Choose the bowl

1. Open **settings** (tap the bowl's name at the bottom of the home screen, or **⋯** then **settings**).
2. Tap one of the five bowls. It plays one strike and becomes the bowl for everything: the repeated bowl, the end of a sitting and the daily times.

### Hear the bowl

Tap **⋯** on the home screen, then **hear the bowl**. In the settings, tapping a bowl also plays it.

### Use your own sound

1. Open **settings** and tap **your own sound…**.
2. Choose an audio file in the phone's file picker.
3. The app keeps its own copy of the file, plays it once, and uses it from then on. Where one strike is due the file is played once; where three bowls are due it is played three times in a row.

To go back to a built-in bowl, tap that bowl. To return to your file afterwards, tap the line with the file's name and choose **use this sound**. To replace it, choose **pick another file…**; the new file takes the place of the old one.

### Set the loudness

The bowl plays on the phone's alarm channel. Its loudness is the phone's alarm volume, not the media or ringtone volume. Use **hear the bowl** to check it.

### Let the app run in the background

1. Open **settings**.
2. Tap **allow running in the background**.
3. Accept the phone's request to stop optimising battery use for this app.

The line then reads **runs in the background: allowed**.

### Switch between white on black and black on white

Tap **⋯** on the home screen and then **black on white** or **white on black**; or, in **settings**, tap the line above **colours**.

### Put the widget on a home screen

1. Add a widget the way your launcher does it and choose **Reader's Mindful Tool** (described as **a bowl every X minutes, a timed meditation — play and stop**).
2. Choose **both**, **a bowl every X minutes only** or **meditation period only**.
3. On each line, tap **−** or **+** to change the minutes and **▶** to start. While it runs the line shows a countdown and **■**; tap **■** to stop.

## Settings

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| Bowl (first block of the settings) | The sound used for every bowl in the app | **Tibetan bowl (E♭)**, **singing bowl**, **gong bowl**, **Satipanya**, **enpleineconscience.ch**, or your own file | **Tibetan bowl (E♭)** |
| **your own sound…** | Uses an audio file from the phone as the bowl | any file the phone can play (mp3, wav) | none |
| **allow running in the background** | Exempts the app from the phone's battery optimisation | allowed or not | not allowed |
| **colours** | The two colours of the app and of its widget | **white on black**, **black on white** | **white on black** |
| **text size** | The size of all text in the app | **small**, **medium**, **large** | **medium** |
| **font** | The typeface of the app | **sans**, **serif**, **mono** | **sans** |
| **haptic tick** | A short vibration when you tap **▶** or **■** in the app | **on**, **off** | **on** |

Two more values are remembered without being in the settings screen: the minutes of **a bowl every** (10 at first) and of **meditate** (20 at first). They are the last ones you set, in the app, on the widget or on the Reader's Launcher tile.

The five built-in bowls are recorded at matched loudness.

## Your data

Everything stays on the phone: the settings, the two numbers of minutes, the list of daily times, the state of a running session, the choice made for each widget, and the copy of your own sound file. The app does not have permission to use the network, so it sends nothing to anyone and receives nothing.

There is no sync, no export and no import. The app does not opt out of Android's own device backup: if you have switched that on in the phone's settings, Android may include the app's data in it.

Your own sound is copied into the app when you choose it. The original file is not changed, and you can move or delete it afterwards without affecting the app.

A running session survives a restart of the phone, a change of time or time zone and an update of the app: the repeated bowl carries on at the same instants as before, a sitting carries on if its end is still ahead, and the daily times are set again. A sitting whose end passed while the phone was off is simply ended, without bowls.

Uninstalling the app removes all of this, including the copy of your sound.

## With the other apps

### Home-screen widget

The widget **Reader's Mindful Tool** works in any launcher. It can be resized and shows one line per function, in the app's colours:

- stopped: the name (**a bowl every** or **meditate**), then **−**, the minutes, **+** and **▶**;
- running: the name, a second line (**next at 14:30 · 2 rung**, or **until 14:50**), a live countdown and **■**; a sitting also shows a thin progress line.

**−** and **+** move through fixed values: 1, 2, 3, 5, 10, 15, 20, 30, 45, 60, 90, 120 minutes for the repeated bowl, and 5, 10, 15, 20, 25, 30, 40, 45, 60, 90, 120 minutes for the sitting. The widget and the app share the same minutes: a number set on the widget is the one the app shows. A number typed in the app reaches the widget the next time the widget is redrawn, that is when a session starts or stops, or within half an hour. Tapping the words opens the app.

What a widget shows (both functions or one) is chosen when it is placed. To change it, remove the widget and place it again.

### Reader's Launcher

Reader's Launcher has a tile called **mindful** that shows the same two functions: both on one tile, with a sideways swipe to go from one to the other, or only one. You tap the words to change the minutes, **▶** to start and **■** to stop. The tile needs Reader's Mindful Tool to be installed.

### Nothing else

The app does not receive shared content and does not open files, apart from the audio file you choose as your own sound.

## Limits

- Minutes go from 1 to 240, in whole minutes, for both functions.
- The repeated bowl is always one strike and the end of a sitting is always three bowls. Only the daily times let you choose between one and three.
- There is no bowl at the start of a sitting, no preparation time and no intermediate bowl inside a sitting, other than by running the repeated bowl alongside it.
- The daily times ring every day. There is no choice of days of the week.
- One bowl serves the whole app; you cannot give a different sound to each function. Only one own sound is kept at a time.
- A bowl that could not sound at its time (the phone was off) is skipped, never rung late.
- If two bowls fall at the same moment, the second cuts off the first.
- There is no volume setting in the app: the phone's alarm volume decides.
- The widget's **+** stops at 120 minutes; larger values, up to 240, are typed in the app.
- No history of sittings, no statistics, no guidance, no export.

## Messages and problems

| What you see | What it means, what to do |
|---|---|
| **(1–240)** added to the title of the minutes prompt | The number is not accepted. Type a whole number from 1 to 240. |
| **(hh:mm)** added to the title of the time prompt | The time is not understood. Type hours from 0 to 23 and minutes from 00 to 59, for example 07:30. |
| **none yet — tap to add a time of day** | No daily time is switched on. Tap the line to add one or switch one back on. |
| **no time set yet** | The list of daily times is empty. Tap **+ new time**. |
| **allow running in the background** | The phone may still restrict the app to save battery. Tap the line and accept. |
| **runs in the background: allowed** | Nothing to do. |
| Notification **the bowl** | A bowl is sounding outside a session; the notification goes away when the sound ends. |

**The bowl is silent or too quiet.** Raise the phone's alarm volume, then try **hear the bowl**.

**Nothing happens after choosing your own file.** The phone could not read it as sound, so the app kept the bowl it had. Choose another file, mp3 or wav.

**A session that was running shows ▶ again when you open the app.** Its alarm had been lost and could not be set again; the app ends such a session rather than show a countdown that would never reach zero. Start it again, and allow running in the background in the settings.

**An alarm icon appears in the phone's status bar.** Each bowl is set as an alarm-clock alarm, the kind the phone rings exactly on time; the phone may show its usual alarm sign for it.

**The bowl rings in silent mode or in Do Not Disturb.** This is intended. To have silence, stop the session and turn off the daily times.

**The widget's + or − does nothing.** The minutes are already at the end of the widget's list of values. While a function runs, **−** and **+** are not shown: the minutes cannot be changed until you stop it.

**The widget still shows the old minutes after you changed them in the app.** The widget catches up when a session starts or stops, or within half an hour. Until then, set the minutes on the widget itself with **−** and **+**.


# Reader's Food Log

*Android 1.2.1*

## What it is

Reader's Food Log is a food diary made only of photos. One touch opens the viewfinder, a second touch takes the photo, and the screen closes by itself; the app labels the photo **breakfast**, **lunch**, **dinner** or **snack** from the time of day and files it under its day. You can also note a physical activity in one tap and your weight once a day, with a curve of how it moves.

It deliberately has no calories, no food database, nothing to type about what you eat, no account and no network access: everything stays on the phone. The app is black and white, text only, and follows the phone's language (English, French, German, Spanish, Portuguese, Russian).

## First start

The app opens straight on its home screen, titled **food log**. There is no account to create and nothing to configure.

The journal is empty: the home screen shows a single line, **today**, with **nothing yet** under it, and three buttons at the bottom: **activity**, **weight** and **photograph**.

The only permission the app uses is the camera, to take the photos. Android asks for it the first time the viewfinder opens. If you refuse, the viewfinder shows **The camera is all this screen does. Touch to allow it.** Touch the screen to be asked again; if Android no longer shows its question, the touch opens the app's page in Android's settings, where you can allow the camera. When you come back, the viewfinder starts.

The app runs on Android 8.0 and later.

## The screens

### Home (food log)

The title **food log** is at the top left, **settings** at the top right. Touch **settings** to open the settings.

Below is the list of days, the most recent first:

- **today** is always the first line, even when it is empty (it then reads **nothing yet**).
- Then come **yesterday** and the earlier days, written in full in lower case (for example "monday 14 september"; a day of another year is written short with its year, "mon 14 sep 2025"). A day appears only if it holds at least one photo, one activity or a weight.
- Under each day, a summary: the number of photos, the number of activities and the weight, for example "3 photos · 1 activity · 72.4 kg".

Touch a day to open it.

At the bottom of the screen, always under the thumb:

- **✎ activity** opens the sheet **physical activity, now**.
- **⚖ weight** opens the weight screen. Once today's weight is entered, this button shows the weight itself (for example "72.4 kg") instead of the word.
- **◉ photograph**, the wide band in reversed colours, opens the viewfinder.

The back button on the home screen leaves the app.

### The viewfinder

The viewfinder fills the screen, always upright (portrait). It uses the back camera, or the front one if the phone has no back camera. The screen stays lit while it is open.

- A band at the top shows the label for the current time (**breakfast**, **lunch**, **dinner** or **snack**).
- A band at the bottom says **touch anywhere**.

Touch anywhere on the screen, or press a volume key (up or down) or the phone's camera key, to take the photo. The phone gives a short vibration, the screen shows a check mark with the label and the time (for example "lunch · 12:34") for about a second, and the viewfinder closes by itself. You are back where you were: the app, the home screen, or the lock screen.

There is no zoom, no flash control, no choice of camera, and no preview to accept or retake. To leave without taking a photo, use the back button.

If the photo could not be taken, the bottom band reads **that did not work — try again**.

The viewfinder can open over the lock screen (from the quick-settings tile). It only adds a photo; it shows nothing of the journal.

### A day

The title is the day's name (**today**, **yesterday**, or the date); touch it, or the arrow in front of it, to go back.

The screen shows, from top to bottom:

- the day's weight, if one was entered, with the word **weight** under it. Touch it to type it again.
- the photos and the activities, mixed, in the order of the clock. Each photo has its label and its time above it (times are on the 24-hour clock). Each activity is a line of text with its time and the word **activity** under it.

An empty day shows **nothing yet**.

**Touch a photo** to open its menu. The menu's title is the time of the photo, and it holds:

- the four labels **breakfast**, **lunch**, **dinner**, **snack**; the current one is marked with a filled dot (●), the others with an empty one (○). Touch a label to give it to the photo.
- **share**: sends the photo to another app through Android's share sheet.
- **delete**: asks **delete this photo?** with **delete for good** and **cancel**.

**Touch an activity** to open its menu, titled with its time and text:

- **change the text**: opens **what did you do?** with the present text, to correct it.
- **delete**: removes the activity at once, without asking.

Touch outside a menu, or press back, to close it without doing anything.

On **today**, the three buttons **activity**, **weight** and **photograph** are at the bottom, as on the home screen. On the other days they are absent: photos and activities are always added to today, at the present time.

### The sheet "physical activity, now"

Opened by **✎ activity**. It offers three one-tap choices, **strength training**, **intense activity** and **endurance**, and below a line, **other…**.

- A touch on one of the three choices records it at the present time and closes the sheet.
- **other…** opens **what did you do?**: type one line, then touch **ok** (or the keyboard's confirm key). **cancel**, back, or a touch outside closes it without recording anything.

### Weight

Opened by **⚖ weight**. If today's weight is not entered yet, the question **weight (kg)** (or **weight (lb)**) is already open with the number pad.

The title **weight** is at the top left (touch it to go back). At the top right is the period shown by the curve; it starts on **90 days**. Each touch moves to the next one: **90 days**, **1 year**, **everything**, **30 days**.

**The curve.** A line through the weights of the period. The highest weight of the period is written at the top left, the lowest at the bottom left, and the most recent weight at the top right. Under the curve, one line gives the change between the first and the last weight of the period, with its sign, and the two days, for example "-1.2 kg · monday 3 august → today". With fewer than two weights in the period, the screen says instead **The curve appears with the second weight.**

**Today's line.** Under the curve, today's weight with **today** under it, or, if there is none yet, **enter today's weight** in reversed colours. Touch it to type or retype today's weight.

**The earlier weights.** The list of all the other days with a weight, the most recent first (whatever period the curve shows). Touch one to open its menu, titled with the day and the weight:

- **change the weight**: opens the question for that day.
- **delete**: removes that day's weight at once, without asking.

**The question.** Its title is **weight (kg)** or **weight (lb)**, followed by **last** and the most recent weight known up to that day (for example "weight (kg) · last 72.4 kg"). Type the number, with a point or a comma for the decimals, then **ok**. The app accepts a weight between 20 and 400 kg (about 44 to 882 lb); with any other value the question simply stays open. **cancel** closes it without changing anything.

### Settings

Opened by **settings** on the home screen. See "Settings" and "Your data" below. The last line shows the app's name and its version number.

## How to

### Photograph what you are about to eat

1. Open the viewfinder: touch **◉ photograph** in the app, or the widget on your home screen, or the quick-settings tile **Food photo**.
2. Aim, then touch anywhere on the screen (or press a volume key).
3. The label and the time appear for a moment, and the screen closes by itself.

The photo is filed under today with the label for the time it was taken.

### Take a photo without unlocking the phone

1. Add the tile **Food photo** to Android's quick settings (pull down the quick settings, edit them, and drag the tile in).
2. Pull the quick settings down and touch **Food photo**.
3. Touch anywhere to take the photo.

### See what you ate on a given day

1. On the home screen, touch the day.
2. Scroll through the photos and activities, in the order of the clock.

### Change the label of a photo

1. Open the day and touch the photo.
2. Touch the right label: **breakfast**, **lunch**, **dinner** or **snack**.

### Share a photo

1. Open the day and touch the photo.
2. Touch **share**, then choose the app to send it with.

### Delete a photo

1. Open the day and touch the photo.
2. Touch **delete**.
3. Touch **delete for good**. The photo cannot be recovered.

### Note a physical activity

1. Touch **✎ activity** (home screen or **today**).
2. Touch **strength training**, **intense activity** or **endurance**.

It is recorded under today at the present time.

### Note an activity in your own words

1. Touch **✎ activity**, then **other…**.
2. Under **what did you do?**, type one line.
3. Touch **ok**.

### Correct or delete an activity

1. Open the day and touch the activity.
2. Touch **change the text**, correct it and touch **ok**; or touch **delete**.

The time of an activity cannot be changed.

### Enter today's weight

1. Touch **⚖ weight**. The question opens by itself if today has no weight yet.
2. Type the number and touch **ok**.

There is one weight per day: typing it again replaces it.

### Correct today's weight

1. Touch the weight at the bottom of the home screen (it has replaced **⚖ weight**).
2. Touch today's line, under the curve.
3. Type the right number and touch **ok**.

You can also open **today** and touch the weight at the top of the day.

### Correct or delete the weight of an earlier day

1. Touch **⚖ weight** (or the weight shown in its place).
2. In the list under today's line, touch the day.
3. Touch **change the weight** and type the new number, or touch **delete**.

### See how your weight moves

1. Touch **⚖ weight** (or the weight shown in its place).
2. Touch the period at the top right to move between **90 days**, **1 year**, **everything** and **30 days**.

### Weigh in pounds instead of kilograms

1. On the home screen, touch **settings**.
2. Touch the line **weight unit**: it switches between **kg** and **lb**.

Every weight already entered is shown in the new unit.

### Move the journal to a new phone

1. On the old phone: **settings**, then **export the journal**. Choose where to save the zip file (its name is proposed as "food-log-" followed by the date). Wait for **journal exported**.
2. Carry the file to the new phone (a cable, a memory card, a cloud folder, a message to yourself).
3. On the new phone, install Reader's Food Log, then **settings**, **import a journal**, and choose the file. The app says how many entries were added.

### Keep a backup copy of the journal

Do step 1 above from time to time and keep the zip file somewhere other than the phone.

### Change the look

In **settings**, touch **colours**, **text size** or **font**; each touch moves to the next choice.

## Settings

The settings screen starts with the reminder **Everything stays on this phone. To move to a new phone, export the journal here and import it there.**

| Line | What it does |
| --- | --- |
| **export the journal**, with **one zip file, where you choose** under it | Writes the whole journal into one zip file at the place you choose. While it runs, the line reads **working…**. |
| **import a journal**, with **adds, replaces nothing** under it | Reads a zip file exported by the app and adds what the phone does not have yet. |

The result of an export or an import is written just below these two lines.

Then the settings themselves. Each line shows the current value in large letters and the setting's name under it; touch the line to move to the next value.

| Setting | Choices | Default |
| --- | --- | --- |
| **colours** | **dark** (white on black), **light** (black on white) | **dark** |
| **text size** | **S**, **M**, **L** | **M** |
| **font** | **sans-serif**, **serif**, **mono** | **sans-serif** |
| **weight unit** | **kg**, **lb** | **kg**; **lb** when the phone's region is the United States, Liberia or Myanmar |
| **vibration on touch** | **on**, **off** | **on** |

**colours** also sets the colours of the two home-screen widgets.

**weight unit** only changes how weights are typed and shown; the journal itself always keeps them in kilograms, so you can switch at any time without losing anything.

**vibration on touch** is the short vibration when you touch **activity**, **weight** or **photograph**. The vibration given when a photo is taken in the viewfinder does not depend on this setting.

Below the settings, a paragraph recalls how the labels are chosen: **The label comes from the time of the photo: breakfast 4:00–10:30, lunch 11:30–14:30, dinner 18:00–22:00, snack the rest of the time. Touch a photo to change it.** These hours cannot be changed.

The last line, **Reader's Food Log**, shows the version number. Touching it does nothing.

## Your data

**Where it lives.** The whole journal is on the phone, in the app's private storage: one folder per day, holding the day's photos, its activities and its weight. The photos do not appear in the phone's gallery. Photos are saved small on purpose (about 1600 × 1200 points), so that the journal and its exports stay light.

**The network.** The app has no network permission: it cannot send or receive anything. There is no account, no synchronisation, no statistics. A photo leaves the app only when you **share** it or when you export the journal.

**Android's backup.** The app is excluded from Android's automatic backup. The only copy of your journal outside the phone is the one you export yourself.

**Export.** **export the journal** writes one zip file containing one folder per day, named by its date; in it, the photos as ordinary JPEG images (named by their time and label), a small text file for the activities and another for the weight in kilograms. You can open the zip on a computer and look at the photos there. The look settings (colours, text size, font, unit, vibration) are not part of the export.

**Import.** **import a journal** merges the file into the journal already on the phone and replaces nothing:

- a photo already on the phone is left as it is, even if its label differs in the file (the phone's label is kept, and the photo is not added twice);
- activities are added one by one, except those the phone already has with the same time and the same text;
- a day that already has a weight keeps it; the file's weight is added only on days without one.

You can therefore import the same file twice, or import onto a phone that already has a journal, without creating duplicates.

**Uninstalling.** Uninstalling the app, or clearing its data in Android's settings, deletes the whole journal. Export it first if you want to keep it.

## With the other apps

### Home-screen widgets

The app offers two widgets for any Android home screen. Both take the colours chosen in the app (**dark** or **light**).

- **Food photo** (one cell): a single ◉. One touch opens the viewfinder.
- **Food log** (four cells wide, one high): the title **food log**, and under it **today** followed by the day's count, for example "today · 2 photos · 1 activity", or "today · nothing yet". Touch the text to open the app. Touch **✎** to open the app on the sheet **physical activity, now**. Touch **◉** to open the viewfinder. The count is brought up to date after each photo or activity.

Both can be resized.

### Quick-settings tile

**Food photo**, to add to Android's quick settings. One touch opens the viewfinder, from any app and from the lock screen.

### Shortcuts on the app's icon

A long press on the app's icon offers two shortcuts: **Photograph** (opens the viewfinder) and **Activity** (opens the app on the sheet **physical activity, now**).

### Reader's Launcher

Reader's Launcher has a **food log** tile. It shows **photograph** with **food log** under it and a ◉; one touch opens the viewfinder. If Reader's Food Log is not installed, the tile shows the app's name in grey and a touch opens the app's page on the web.

### Sharing

**share** on a photo hands the image to any app that accepts pictures (messages, mail, notes). The app does not receive anything from other apps, and opens no file other than its own journal zip.

## Limits

- Photos only: no text, no calories, no nutrients, no caption on a photo.
- Photos are taken in the app's viewfinder; you cannot add a picture from the gallery or from another app.
- Photos and activities are always recorded at the present time, under today. You cannot add a photo or an activity to an earlier day, nor change the time of an entry.
- The four labels and their hours are fixed.
- One weight per day. You can correct the weight of a day that has one, but not add a weight to an earlier day that has none.
- Today's weight can be retyped but not removed; **delete** is offered for the earlier days only.
- Deleting an activity or a weight is immediate, without confirmation; only photos ask **delete this photo?**.
- A weight must lie between 20 and 400 kg.
- An activity is one line of text.
- The curve's period goes back to **90 days** each time the weight screen is opened.
- No search, no statistics on meals, no reminders or notifications.
- No synchronisation between phones: the journal moves by export and import.
- The viewfinder has no zoom, no flash control and no camera choice, and works upright only.
- There is no language setting: the app uses the phone's language, or English if that language is not one of its six.

## Messages and problems

| Message | What it means, what to do |
| --- | --- |
| **nothing yet** | Nothing recorded on that day. On the home screen and the widget it concerns today. |
| **touch anywhere** | The viewfinder is ready: touch the screen or press a volume key. |
| **The camera is all this screen does. Touch to allow it.** | The camera permission is missing. Touch the screen: Android asks again, or the app's page in Android's settings opens so that you can allow the camera there. |
| **that did not work — try again** | In the viewfinder: the camera could not start or the photo could not be saved. Touch again; if it persists, close the viewfinder and reopen it. In the settings: the export file could not be written; choose another place and export again. |
| **The curve appears with the second weight.** | The period shown holds fewer than two weights. Enter a weight on another day, or choose a longer period at the top right. |
| **working…** | An export is being written. Wait for the result. |
| **journal exported** | The zip file is written where you chose. |
| "3 entries added" (the number varies) | The import added that many photos, activities and weights. |
| **nothing new in this file** | The file is a journal, but the phone already has everything in it. |
| **this file is not a food log journal** | The file is not a zip exported by Reader's Food Log, or it could not be read. Choose the right file. |

**The weight question does not close when I touch ok.** The number is outside 20 to 400 kg (44 to 882 lb), or is not a number. Check the unit shown in the question's title, **weight (kg)** or **weight (lb)**, and type it again.

**ok does nothing in "what did you do?".** The line is empty; type something, or touch **cancel**.

**The label is wrong.** The label follows the clock: breakfast from 4:00 to 10:30, lunch from 11:30 to 14:30, dinner from 18:00 to 22:00, snack otherwise. Touch the photo and choose another label.

**My photos are not in the gallery.** That is intended: they are kept inside the app. Use **share** on a photo, or **export the journal**, to get them out.


# Reader's Scanner

*Android 1.1.2 · Windows, macOS, Linux 1.0.2*

## What it is

Reader's Scanner turns paper into searchable PDFs. On the phone you photograph the pages with the camera: the app finds the page, straightens it, cleans it and reads its text. On the computer the same app drives a real scanner (glass or sheet feeder). Each document becomes one PDF whose text can be searched and copied, named with its date and hour and, if you wish, a name of your own, and filed in plain folders.

The text is always read on your own device: your documents are never sent anywhere to be read. If you enter a WebDAV folder of your own (kDrive, Nextcloud or any WebDAV server), the phone and the computer show the same documents and the same folders.

The app is black and white and made of text. It has no account, no advertising, no cloud of its own, and it does not name documents for you: a document you do not name is called by its date and hour.

## First start

### On the phone: which engine?

The first screen is **Which engine?**. It explains: **Two ways of finding the page and reading its text. Both work on the phone: your documents are never sent to be read.** You choose one of two entries by touching it (each ends with **→ this one**):

- **Google ML Kit (recommended)**: **Finds and straightens pages most reliably, on any background, and reads text very well. Closed Google code: it needs Google Play services and sends usage statistics to Google (not your documents). Latin script only: Russian is read by Tesseract.** On a phone without Google Play services this entry is greyed out and reads **Not available on this phone: Google Play services are missing.**
- **Open source**: **The app's own page finder and Tesseract: free software, nothing goes to Google, seven languages. Less sure of the page on pale backgrounds (the corners are easy to adjust), blurred shots are flagged at once.**

The screen ends with **You can change this at any time in the settings.** The choice sets two settings at once, **finding the page** and **reading the text**, which you can later change separately.

### Permissions on the phone

- **Camera**: asked the first time the app's own capture screen opens. It is used only to photograph pages. If you refuse, the capture screen shows **This screen needs the camera. Touch to allow it.**; touching it asks again, or opens the app's page in Android's settings when Android no longer asks.
- **Network access**: used only for your WebDAV folder (if you set one), to download a "best" reading model when you ask for one, and by Google ML Kit for its usage statistics if you chose it.

The app asks for no access to your files or photos: photos are picked through Android's own photo picker.

### What you see when it is empty

The home screen shows one folder, **all scans**, with the number 0, a dashed tile **new folder**, and a wide bar **+ new scan** at the bottom. An empty folder shows **No scans here yet.**

No account or server is needed. The WebDAV folder is optional and is entered in the settings (see "Set up the WebDAV folder").

## The screens

These are the screens of the phone. The computer's window is described in "On the computer".

A menu is a sheet of text lines at the bottom of the screen; touching outside it, or the back button, closes it.

### Home

The title is **scanner**. On its right, **⌕** opens the search and **⋯** opens the settings.

Below, a grid of folders, two per row. Each shows the number of documents it holds and its name.

- **all scans** (drawn filled) holds every document, whatever its folder. Touch it to list them all.
- Your folders: touch one to open it; a long press opens a menu with **rename** and **delete the folder**.
- **new folder** (dashed): touch it, type the **name of the new folder**, then **ok**.

At the bottom, **+ new scan** opens the capture screen.

### A folder

The title is the folder's name; touching it (or **←**) goes back. **⌕** opens the search.

Documents are listed newest first. Each row shows a small picture of the first page, the document's name (or its date and hour if it has no name), then a line with the date and hour, the number of pages and, in **all scans**, the folder's name. A third line may say **reading the text 2/5**, **text to be read** or **text could not be read**. A document scanned on another device shows the word PDF in place of the picture until its PDF has been downloaded.

Dates are written **today 11:32**, **yesterday 09:10**, or the day and month.

- Touch a row to open the document.
- A long press on a row starts a selection. The title becomes **1 selected**, **2 selected**…; touches then add or remove documents; **all** selects everything and becomes **none**. A bar at the bottom offers **share**, **move**, **delete** and, when exactly one document is selected, **⋯** (the document's menu). The back button or **←** ends the selection.

At the bottom, **+ new scan** opens the capture screen; the document will be offered this folder first.

### Capture (the app's own camera)

This screen is shown when **finding the page** is set to **built-in (free software)**. It is always upright; if you hold the phone sideways the photo follows your hand. The screen stays lit.

- At the top, seven language buttons: **EN FR DE IT ES PT RU**. The one that is filled is the language the text will be read in; the line below confirms it, for example **text read in English**.
- On phones with a flash, **☼** at the top right turns the lamp on (**☀**) and off.
- In the middle, the camera's view. When the app sees the page it outlines it in white.
- Under the view, one line of guidance: **hold the page in view, touch to take it**, then **page found — touch or press a volume key**, then **hold still…** while the app waits for your hands to stop moving and focuses on the page. **the camera did not answer — try again** means the photo failed.
- To take the page: touch the view, touch the round button, or press a volume key.
- Bottom left: **from photos** (before the first page) brings in pictures from your gallery. Once a page is taken, a small picture of the last page with the number of pages replaces it; touching it opens the review.
- Bottom right: **done →** opens the review.

If a page comes out blurred, a white bar says so at once, for example **page 2 is blurred**, with **retake** (the next photo takes that page's place) and **keep** (the page stays as it is).

The back button leaves the capture if no page was taken; otherwise it opens the review.

### Capture with Google's scanner

When **finding the page** is set to **ML Kit (Google)**, **+ new scan** opens Google's own scanner screen instead, with its own buttons. When you finish there, the pages arrive in the review described below. Because Google's screen has no language buttons, the review of a new document then shows the seven language buttons at its top, with the line **text read in …**.

### Review

The title says where you are: **page 2 of 5**, followed by **· blurred** if this page is blurred, or by **· 1 blurred** if another page is. Swipe sideways to go from page to page.

Under the page, four buttons:

- **crop** opens the crop screen for this page.
- **turn** turns the page a quarter turn.
- The third button shows the page's look and changes it at each touch: **clean** (white paper, colours kept), **grey**, **b & w**, **photo** (the straightened page as the camera saw it).
- **⋯** opens a menu titled with the page number: **move earlier**, **move later**, **« clean » for every page** (the current look, given to all pages), **from photos**, **take this page again**, **delete this page**.

At the bottom, **+ page** returns to the capture, and **save** files the document. **save** reads **working…** while pages are still being prepared.

A page may carry a small label: **straightening…** while it is being made, **this photo could not be read** if the picture could not be used, **blurred — ⋯ to take it again** if it is blurred.

The back button asks **discard this page?** or **discard these 3 pages?** (when editing an existing document: **discard these changes?**), with **discard** and **keep them**.

### Crop

The whole photo is shown, with the page's outline and a round handle on each corner. The line at the top says **drag the corners onto the corners of the page**. While you drag a corner, a magnifier in a top corner of the picture shows it three times larger.

- **whole photo** puts the corners on the corners of the photo.
- **find the page** lets the app look for the page again (**searching…**). If it finds none: **no page found in this photo — place the corners by hand**.
- **cancel** leaves without change; **ok** applies the new outline.

### Filing sheet

**save**, for a new document, opens a sheet with:

- **name this document**: a field (it shows **optional** while empty), with the keyboard already open. Below it: **The file name starts with the date and hour; the name follows them. Without a name, they stand alone.**
- **file in**: **▣ all scans**, then one line per folder (**▢** and its name), then **+ new folder**. If the scan was started from inside a folder, that folder comes first and is highlighted, and the list ends with **▣ no folder (all scans only)**.

Touching a line files the document there. **+ new folder** asks for the **name of the new folder** and files the document in it. The app then shows the folder the document went into, and the text is read in the background.

Touching outside the sheet closes it without filing.

### A document

The title is the document's name (or its date). Under it, one line of information: date and hour, number of pages, language of the text, who read it (**Tesseract fast**, **Tesseract best** or **ML Kit (Google)**), and when it applies **scanned elsewhere**, **reading the text 2/5**, **text to be read** or **text could not be read**.

The pages are shown one under the other. Touch a page to see it full screen.

At the bottom:

- **share** opens the share menu.
- **text** shows the text read on the pages, which you can select and copy; the button then reads **pages** to come back. With several pages, each page's text is headed **— 1 —**, **— 2 —**… If there is nothing to show: **The text has not been read yet.** or **No text was found on these pages.**
- **+ page** opens the capture to add pages.

**⋯** at the top right opens the document's menu, titled with the full file name: **share…**, **open with…**, **save a copy of the pdf**, **rename**, **move to a folder**, **edit the pages**, **read the text again**, **delete**.

A document scanned on another device has no **+ page**, **edit the pages** or **read the text again**: its pages can only be changed where it was scanned. Its PDF is downloaded the first time you open it; the information line then says **downloading the PDF… 40 %**.

### A page, full screen

The page on a black background, with **← 2 / 5** at the top (touch it to go back). Swipe sideways for the other pages. Pinch to zoom (up to six times); a double tap zooms in, a second one zooms out.

### Share menu

Titled with the file name, or **3 documents** when several are selected:

- **PDF**: **the pages with their text, searchable** (for several: **one PDF per document, text searchable**).
- **images**: the pages as pictures; the line says how many, for example **3 JPEG pictures**.
- **text**: **the words read on the pages**. If some text is not ready: **some text is not read yet**.

Android's share sheet then lets you choose the receiving app.

### Search

The field says **search names and text**. Results appear as you type: the document's name and a few words around the place where the text matches. **nothing found** when there is no match. Touch a result to open the document.

### Settings

See "Settings" below. Each line shows its current value in large type and its name underneath; touching the line changes the value or opens a field.

## How to

### Scan a document

1. Touch **+ new scan** (on the home screen, or inside the folder the document belongs to).
2. Check the language at the top (**EN FR DE IT ES PT RU**) and touch another one if needed.
3. Hold the phone over the page until it is outlined, then touch the view or press a volume key. Keep still until the flash on the screen.
4. Repeat for each page.
5. Touch **done →**. Go through the pages; correct what needs it.
6. Touch **save**. Type a name if you want one, then touch the folder.

The document appears in its folder with **text to be read**, then **reading the text 1/3**… When that line disappears, its PDF is searchable.

### Scan with Google's scanner

1. In the settings, set **finding the page** to **ML Kit (Google)**.
2. Touch **+ new scan** and follow Google's screen.
3. Back in the review, choose the language of the text at the top, then **save**.

If Google's scanner cannot start, the app says **Google scanner unavailable — the app's own camera instead: …** and opens its own capture screen.

### Turn photos you already have into a document

1. Touch **+ new scan**, then **from photos** at the bottom left. (In the review: **⋯**, then **from photos**.)
2. Pick the photos (up to 30 at a time).
3. The app finds the page in each one. Check them in the review, then **save**.

### Retake a blurred page

- On the capture screen, when the bar **page 2 is blurred** appears: touch **retake** and photograph the page again. Touch **keep** if the page is fine as it is (a page that is mostly a photograph may be flagged wrongly).
- In the review: go to the page, touch **⋯**, then **take this page again**. The new photo takes the place of the old one.

### Correct the outline of a page

1. In the review, go to the page and touch **crop**.
2. Drag each corner onto the corner of the sheet, using the magnifier.
3. Touch **ok**.

### Turn, reorder or remove pages, change their look

In the review: **turn** turns the page; the look button goes through **clean**, **grey**, **b & w**, **photo**; **⋯** gives **move earlier**, **move later**, **« … » for every page** and **delete this page**.

### Change the pages of a document already filed

1. Open the document, touch **⋯**, then **edit the pages**. To add pages only, touch **+ page** at the bottom of the document.
2. Change what you want in the review, then **save**.

The document keeps its name, date and folder. Its text is read again, in the language currently chosen for the text.

### Name or rename a document

- When filing: type the name in **name this document** before touching the folder.
- Later: open the document, **⋯**, **rename**. The field is titled **name (empty: the date alone)**: empty it to go back to the date alone.

The file is always called date, hour, then name, for example `2026-09-24 11h32 Electricity bill.pdf`.

### Create, rename or delete a folder

- Create: **new folder** on the home screen, or **+ new folder** in the filing sheet.
- Rename: long press on the folder, **rename**.
- Delete: long press on the folder, **delete the folder**. The app asks **delete the folder « … »? Its scans stay in all scans.** Touch **delete the folder, keep the scans**. The documents are not deleted; they remain in **all scans**.

### Move documents to another folder

- One document: open it, **⋯**, **move to a folder**, then touch the folder (**●** marks the current one). **no folder (all scans only)** takes it out of its folder.
- Several: in a folder, long press on one document, touch the others, then **move** and the folder.

### Read, copy or re-read the text

- Open the document and touch **text**. Press and hold on the text to select and copy it.
- If the text is wrong because the language was wrong: **⋯**, **read the text again**, then the language under **read the text again in**. Each language shows which reader will be used.

### Find a document

Touch **⌕**, type one or several words. A document is found when every word is in its name, its date or its text, in any order; capitals and accents do not matter.

### Share documents

1. Open the document and touch **share** (or select several documents in a folder and touch **share**).
2. Choose **PDF**, **images** or **text**.
3. Choose the app to send to.

Shared text is sent as a message; a very long text (over 60 000 characters) is sent as a text file instead.

### Open the PDF in another app, or save a copy

Open the document, **⋯**, then **open with…** (Android offers your PDF apps) or **save a copy of the pdf** (you choose where to save it).

### Delete documents

- One: open it, **⋯**, **delete**, then **delete for good** under **delete this document?**.
- Several: select them in a folder, **delete**, then **delete for good** under **delete these 3 documents?**.

With a WebDAV folder, the document is also deleted from the server and from your other devices.

### Set up the WebDAV folder

1. Home, **⋯** (settings).
2. Touch **server** and type the address, which begins with https://. For kDrive the app gives: **https://ID.connect.kdrive.infomaniak.com (the ID is the number in the kDrive web address)**.
3. Touch **username**, then **password**. For kDrive: **your Infomaniak login, and an application password if two-factor authentication is on**.
4. **folder on the server** is **Scans** unless you change it.
5. Touch **send now**. The line under it says **sending…**, then **up to date at 11:32**, followed when it applies by **2 sent**, **1 removed**, **3 received**.

### Copy the server settings to another device

- On the device already set up: settings, **export credentials** (**a file to set up another device — it holds the password**), and send the file to yourself by a private route.
- On the other device: settings, **import credentials**, and pick the file. The line then says **credentials imported**.

A credentials file exported by Reader's Notes or Reader's Recorder also works: **server and login taken from Reader's Notes — the folder stays yours**. One from Reader's Tasks or Reader's Calendar gives the login only: **login taken from Reader's Tasks — now enter the WebDAV server**.

### Get a more accurate reading (Tesseract)

In the settings, under **More accurate reading: the "best" model of a language, downloaded once (slower, and larger).**, touch the line of the language: **fast model — download the best one (4 MB)**. It shows **downloading the best model… 40 %**, then **best model in use — touch to remove it**. **other languages…** shows the other six languages.

### Change the engine

In the settings, touch **finding the page** to switch between **built-in (free software)** and **ML Kit (Google)**, and **reading the text** to switch between **Tesseract (free software)** and **ML Kit (Google)**. The two are independent.

## Settings

The settings of the phone, in the order of the screen. Touching a line with a fixed list of values moves to the next value.

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **server** | Address of your WebDAV server | free text, https://… | empty |
| **username** | Login on that server | free text | empty |
| **password** | Password (shown as dots) | free text | empty |
| **folder on the server** | Folder that receives the scans | free text | **Scans** |
| **send when the app opens** | Syncs with the server each time the app comes to the front | **on**, **off** | **on** |
| **send now** | Syncs at once; the result is shown under it. Shown only when a server is set | | |
| **export credentials** | Shares a file holding server, folder, login and password. Shown only when a server is set | | |
| **import credentials** | Reads such a file | | |
| **page format** | Paper you usually scan. **A page of that paper then gets its exact proportions, and the PDF its size. Receipts, cards and other shapes keep their own.** | **automatic (any sheet)**, **A series (A4, A5, A3)**, **US Letter** | **automatic (any sheet)** |
| **look of new pages** | Look given to each new page until you change it in the review | **clean**, **grey**, **b & w**, **photo** | **clean** |
| **language of the text (also on the capture screen)** | Language the next scans are read in | English, français, Deutsch, italiano, español, português, русский | the phone's language if it is one of these, otherwise English |
| "best" model lines | Download or remove the more accurate Tesseract model of a language | per language | fast model |
| **finding the page** | Who finds and straightens the page | **built-in (free software)**, **ML Kit (Google)** | your first-start choice |
| **reading the text** | Who reads the text | **Tesseract (free software)**, **ML Kit (Google)** | your first-start choice |
| **colours** | White on black or black on white | **dark**, **light** | **dark** |
| **text size** | Size of the app's text | S, M, L | M |
| **font** | Typeface of the app | sans-serif, serif, mono | sans-serif |
| **vibration on touch** | A short vibration on buttons | **on**, **off** | **on** |

Explanations shown on the screen:

- Under the language: **The text is read on this phone, never sent anywhere to be read. Clean: white paper, colours kept. Grey and b & w suit plain text. Photo: the straightened page as the camera saw it.**
- Above the two engine lines: **Each step can use Google's ML Kit or the free engines. ML Kit's scanner needs Google Play services and shows its own screen (the language is then chosen in the review); its reader knows the Latin script only (Russian is read by Tesseract). It sends usage statistics to Google, never your documents.**

The "best" models weigh: English 15 MB, français 4 MB, Deutsch 9 MB, italiano 9 MB, español 14 MB, português 8 MB, русский 15 MB.

The last line shows the app's name and version, followed by the credits: **Text recognition: Tesseract 5 and Leptonica (Apache 2.0) through Tesseract4Android, language models tessdata (Apache 2.0); or Google ML Kit (Google's terms), if chosen.**

## Your data

### Where it lives

On the phone, everything is kept in the app's private storage: the photos as taken (so that a page can be cropped again later), the pages as shown, the text, and the PDF. Android's backup is switched off for this app. Uninstalling the app removes all of it from the phone; what was sent to your WebDAV folder stays there.

On the computer, see "On the computer".

### What goes over the network

- To your WebDAV server, if you set one: the PDFs and a small description of each document (which contains its text). Nothing is sent before a server is entered.
- To github.com, only when you download a "best" reading model: the model file of the Tesseract project is fetched from there.
- To Google, only if you chose ML Kit: usage statistics, according to the app's own notice; never your documents.

The text is read on the device in every case.

### The WebDAV folder

In the folder you named (**Scans** by default) you will find:

- one subfolder per folder of the app, holding its PDFs;
- directly in the folder, the PDFs that are in **all scans** only;
- a hidden folder `.readers-scanner` with one small description file per document: its name, date, folder, language and text. It is what lets another device list and search a document without downloading its PDF.

PDFs you put in that folder yourself, without a description, are left alone and are not shown in the app.

### How the sync behaves

The phone syncs when the app opens (if **send when the app opens** is **on**), after a document is filed, once its text is read, after every rename, move or deletion, and when you touch **send now**.

- A document goes up once its text has been read (or could not be read), never before.
- Renaming or moving a document renames or moves its file on the server; the PDF is not sent again. If a file of that name already exists there, " (2)" is added to the name.
- Documents scanned on another device appear in the list at once, marked **scanned elsewhere**, and can be searched. Their PDF is downloaded when you open, share or save them. You can rename, move, share and delete them; a device never sends the PDF of a document it did not scan.
- Changed on two devices: the latest change wins.
- Deleted on one device: deleted on the others, unless it was changed there in the meantime, in which case it comes back.
- Folders: a folder created on either side appears on the other. A folder deleted on the server disappears from the app; its documents stay in **all scans**. A folder deleted or renamed in the app is removed from the server once no file is left in it.

### The credentials file

**export credentials** makes a file named `readers-credentials-scanner.json` and hands it to Android's share sheet. It holds the server, the folder, the login and the password in clear text: send it only by a route you trust, and delete it afterwards. The copy the app made for sharing is erased at the next export and at each start of the app.

## With the other apps

- **App shortcut**: a long press on the app's icon offers **New scan**, which opens the capture directly.
- **Sharing**: documents leave as PDF, JPEG pictures or text through Android's share sheet; **open with…** hands the PDF to any PDF app.
- **Credentials**: the credentials file is the same for the Reader's apps. Reader's Scanner reads the server and login from a file exported by Reader's Notes or Reader's Recorder, and the login alone from Reader's Tasks or Reader's Calendar.
- **The computer**: the desktop app shares the same WebDAV folder (next section).

The app offers no home-screen widget and does not appear in the share menu of other apps.

## On the computer

The desktop app (Windows, macOS, Linux) does the same job with a real scanner: one window, one **scan** button, the same folders as the phone. Its window follows the system language (English, French, German, Spanish, Portuguese, Russian).

### How it differs from the phone

- Pages come from a scanner or from files, not from a camera. There is no crop screen, no blur warning and no choice of engine: the text is read by Tesseract.
- Most scanners made since about 2015 (AirScan, Mopria) are found by themselves, on the network or by USB. The others need NAPS2, a free program you install separately from naps2.com.
- The looks are **as scanned**, **clean**, **grey**, **b & w**; the default is **as scanned**.
- From the feeder, blank sheets and blank backs are left out, and pages fed upside down or sideways are set upright.
- There is no share menu: you open the PDF, save a copy, save the pages as pictures, or copy the text.

### First start

The window opens with **put the pages on the scanner, press « scan »** and, under it, **In the feeder or on the glass: the scanner takes what it finds. The text is read on this computer, and the document becomes a PDF you can search.**, with the buttons **scan** and **from files…**. Once you have documents, it says **scan, or choose a document**.

The app looks for a scanner by itself: the bottom left says **looking for the scanner…**, then the scanner's name, or **no scanner found yet**. Nothing has to be set up to scan. The second line says **on this computer only** until you enter a WebDAV folder.

### The window

On the left, from top to bottom:

- **find**: the search field.
- The list. At first it shows **all scans**, your folders (each with its number of documents) and **+ new folder**. Click a folder to list its documents, newest first; a bar **← all scans** (or the folder's name) at the top goes back. When pages are scanned but not yet filed, a line **scan not filed yet** stays at the top of the list.
- Three choices, each a click away: **from: automatic ▾** (**automatic**, **glass**, **feeder**, **both sides**), **look: as scanned ▾**, **text: English ▾** (the language the text is read in).
- The big **scan** button. During a scan it reads **cancel**.
- Two status lines and **⚙**. The first line names the scanner (click: settings). The second is the sync: **on this computer only**, **syncing…**, or **synced 14:05** followed by the numbers sent (↑), received (↓) and removed (−); click it to sync now. **⚙** opens the settings.

On the right: a message, the open document, or the pages just scanned.

In the list:

- Click a document to show it on the right. Double-click (or Enter) opens its PDF in your PDF viewer.
- Ctrl-click or Shift-click selects several documents.
- Right-click a document (or a selection) for its menu; right-click a folder for **rename…** and **delete the folder**; right-click **all scans** for **+ new folder**; right-click the empty part of the list for **scan** and **from files…**.

### A document

At the top its name and **⋯**; under it the date, number of pages, folder, language, reader (**Tesseract** or **Tesseract best**) and, when it applies, **scanned elsewhere**, **reading the text 2/5**, **text to be read**, **text could not be read**, **downloading… 40 %**. Then the pages, one under the other.

At the bottom: **open the PDF**, **save a copy…**, **copy the text**, and **text** (which becomes **pages**) to read the text in place of the pages.

The **⋯** menu (and the right-click menu): **open the PDF**, **save a copy…**, **save the pages as pictures…**, **copy the text**, **rename…**, **move to** (with **no folder (all scans only)**, your folders and **+ new folder…**), **edit the pages**, **add pages from the scanner**, **read the text again in** (the seven languages), **delete**. The **⋯** menu adds **from files…**, **sync now** (when a server is set), **white on black** or **black on white**, and **settings**.

### Scan a document

1. Put the sheets in the feeder or a page on the glass.
2. If needed, change **from**, **look** and **text** above the button. **automatic** takes the feeder when it holds paper, the glass otherwise.
3. Click **scan** (or Ctrl+N). The right side shows **scanning…**, with **from the feeder**, **from the glass** or **both sides**, then **page 1**, **page 2**…, then **setting the pages upright…**. **cancel** (or Escape) stops the scan.
4. The pages appear as small sheets. Under each: its number, **←** and **→** (move earlier, move later), **⟳** (turn), **✕** (delete this page). The dashed sheet **+ page** scans one more page. At the top you can still change **look** (for all pages of this scan) and **text**. If blank pages were left out, **1 blank page left out · keep it** puts them back.
5. The name field (**name this document — or leave it to its date**) already has the keyboard: type a name or leave it empty.
6. Click the folder (**all scans**, one of your folders, or **+ new folder**), or press Enter. The line under the folders tells where Enter files it: **a click on a folder files the document there · Enter: « all scans »**. Enter uses the folder open in the list, otherwise the last folder used.

The document opens on the right and its text is read. **discard** (or Escape) throws the pages away after asking **Discard this page?** or **Discard these 3 pages?** (when you were editing a filed document, it leaves the document as it was, without asking). Pages not yet filed are kept if you close the app.

Scans are made at 300 dpi in colour.

### Bring in pictures and PDFs

Drop files on the window, press Ctrl+O, or choose **from files…**. Accepted: JPEG, PNG, TIFF, BMP, WebP and PDF. The app says **bringing the pages in…**, then shows the pages in the same review as a scan.

### Change a document already filed

- **edit the pages** opens its pages in the review (turn, reorder, delete, look); **add pages from the scanner** does the same and starts a scan. Finish with **save**.
- **rename…** (F2): the field is titled **name (empty: the date alone)**.
- **move to**, **read the text again in**, **delete** (the app asks **Delete “…”?** or **Delete these 3 documents?**).
- **save a copy…** saves the PDF where you choose; with several documents selected it asks for a folder (**save the copies in…**). **save the pages as pictures…** writes one JPEG per page in the folder you choose. **copy the text** puts the text on the clipboard (**text copied**).

Folders: **+ new folder** asks **name of the new folder**; **rename…** asks **new name of the folder**; **delete the folder** asks **Delete the folder “…”? Its scans stay in all scans.**

### Search

Type in **find** (Ctrl+F). The list shows the documents that contain every word, in their name or text, with a few words around the match; **nothing found** otherwise. Escape empties the field; the Down arrow or Enter moves to the first result.

### Settings on the computer

**⚙**, Ctrl+, or **settings** in the **⋯** menu. Changes apply with **save**; **cancel** leaves them.

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **server** | WebDAV address (the field shows the form of a kDrive address as an example) | free text | empty |
| **username**, **password** | Login on that server | free text | empty |
| **folder on the server** | Folder shared with the phone | free text | Scans |
| **import credentials…**, **export credentials…** | Read or write a Reader's credentials file | | |
| **scanner** | The scanner used. **look again** searches again (**looking…**) and lists what it found | the scanners found | the first one found |
| **page format** | Paper size asked of the scanner and given to the PDF | **automatic (A4 here)** or **automatic (Letter here)**, **A series (A4)**, **US Letter** | automatic: Letter in the United States, Canada, Mexico, the Philippines, Chile and Colombia, A4 elsewhere |
| **reading** | **the most accurate models (fetched once per language, 4 to 15 MB)** | ticked, not ticked | ticked |
| **font** | Typeface of the window | sans-serif, serif, mono | sans-serif |

Under **scanner**, a line says **NAPS2 … is here, for the scanners that do not answer by themselves** or **NAPS2 is not installed: only the scanners that do not answer by themselves (AirScan) need it.** with a link to naps2.com.

Under **reading**, a line gives the state for the current language: **English: the best model is here**, **English: downloading the best model… 40 %**, **English: the standard model for now**, **English: its model will be fetched at the first reading**, or **Tesseract is not installed: the pages are kept without their text**.

The bottom of the window shows the version.

Two settings are not in that window: the colours (Ctrl+T, or **white on black** / **black on white** in the **⋯** menu; black on white at first) and the text size (Ctrl+= and Ctrl+-).

To use the phone's folders, enter the same server, folder and login as on the phone, or import the credentials file exported by the phone. If the app's own section is missing from the file, the server and login of Reader's Notes or Reader's Recorder are used: **server and login taken from Reader's Notes**. **export credentials…** writes `readers-credentials.json` in your home folder unless you choose another place; if that file already exists and is a Reader's credentials file, the app's section is added to it and the other apps' sections are kept. The app then says **credentials exported to … — the file holds your passwords: keep it private**.

### Keyboard shortcuts

| Keys | Action |
|---|---|
| Ctrl+N | scan (during a scan: cancel) |
| Enter, in the name field | file the scan in the folder named under the folders |
| Ctrl+O | bring in pictures and PDFs |
| Ctrl+F | search |
| F2 | rename the open document |
| Delete | delete the open or selected documents |
| F5 or Ctrl+R | sync now |
| Ctrl+T | white on black / black on white |
| Ctrl+= or Ctrl++, Ctrl+- | larger, smaller text |
| Ctrl+, | settings |
| Escape | cancel the scan; else empty the search; else discard the pages in review; else go back to the folders |
| Ctrl+Q | quit |

### Sync on the computer

The rules are those of the phone (see "Your data"). The computer syncs at start, every five minutes, after every change, once a text is read, and on F5. When you close the window, the app finishes reading the texts and syncs once more before it quits.

If you change the server or the folder in the settings, the documents scanned on other devices are removed from this computer (they belong to the old server), and the documents scanned here are sent to the new one.

### Command line

- `readers-scanner --export-credentials FILE` writes the credentials file.
- `readers-scanner --import-credentials FILE` reads one.

### Where things are kept

| System | Settings | Documents |
|---|---|---|
| Linux | `~/.config/readers-scanner/config.json` | `~/.local/share/readers-scanner` |
| Windows | `%APPDATA%\Readers Scanner` | the same folder |
| macOS | `~/Library/Application Support/readers-scanner` | the same folder |

The settings file holds the WebDAV password in clear text; on Linux and macOS it is readable by you alone. The documents folder holds, for each document scanned here, the scan as it came, the page as shown, the text and the PDF; for a document scanned elsewhere, its description, its text and, once opened, its PDF. A file `errors.log` there records unexpected errors. Uninstalling the app does not delete these folders.

The "best" reading models are downloaded from github.com (the Tesseract project) into the documents folder. Apart from that and your WebDAV server, the app contacts only your scanner.

## Limits

- Seven languages for the text: English, French, German, Italian, Spanish, Portuguese, Russian. One language per document.
- Google ML Kit reads the Latin script only; Russian is always read by Tesseract. ML Kit's scanner needs Google Play services.
- Folders are one level deep: no folder inside a folder.
- A folder name keeps at most 60 characters, a file name 120; the characters \ / : * ? " < > | are replaced by spaces. Two folders cannot differ only by capitals.
- The app does not invent names: without a name, a document is called by its date and hour.
- On the phone, photos are imported 30 at a time at most.
- The phone accepts only an https:// server address.
- The pages of a document can be changed only on the device that scanned it. Elsewhere it can be read, searched, renamed, moved, shared and deleted.
- On the phone there is no export other than PDF, JPEG pictures and text, and the phone does not take in PDFs. The computer takes in pictures and PDFs.
- The capture screen of the phone works upright only.
- The computer version has no crop and no blur check. According to its own documentation it has been tried on one real scanner, on Linux; the Windows and macOS versions pass the same tests but had not yet been tried with a real scanner.

## Messages and problems

### On the phone

| Message | Meaning, and what to do |
|---|---|
| **This screen needs the camera. Touch to allow it.** | The camera permission is missing. Touch the message. |
| **the camera did not answer — try again** | The photo failed. Take it again; leave the capture and come back if it persists. |
| **hold still…** | The app waits for the phone to stop moving before taking the photo. |
| **page 2 is blurred** / **blurred — ⋯ to take it again** | The page seems blurred. **retake**, or **keep**. |
| **this photo could not be read** | The picture could not be used. Delete the page and take it again. |
| **no page found in this photo — place the corners by hand** | The app did not find the sheet. Drag the corners yourself, or use **whole photo**. |
| **working…** (in place of **save**) | Pages are still being prepared. Wait a moment. |
| **text to be read** | The document waits for its text to be read. It is taken up again at the next start if the app was closed. |
| **text could not be read** | Reading failed. Try **read the text again**. The PDF exists, without searchable text. |
| **The text has not been read yet.** / **No text was found on these pages.** | Shown in the **text** view. |
| **some text is not read yet** | In the share menu: the text shared may be incomplete. |
| **Google scanner unavailable — the app's own camera instead: …** | Google's scanner could not start; the app uses its own camera. |
| **Not available on this phone: Google Play services are missing.** | ML Kit cannot be chosen on this phone. |
| **download failed — touch to try again** | A "best" model could not be downloaded. Check the connection and touch the line. |
| **sending…**, **up to date at 11:32** | The sync is running; the sync succeeded. |
| **not sent: wrong username or password** | The server refused the login. Check **username** and **password** (kDrive with two-factor authentication: an application password). |
| **not sent: no connection to the server** | No network, or a wrong server address. |
| **not sent: this phone cannot talk to the server** | This phone cannot send the requests WebDAV needs. |
| **not sent:** followed by something else (for example HTTP and a number) | The server's own answer. Check the address and the folder. |
| **scanned elsewhere** | The document was scanned on another device. |
| **the PDF is not on the server (any more)** | The PDF of a document scanned elsewhere was moved or deleted there. The next sync sorts it out. |
| **scanned elsewhere: its PDF needs the WebDAV folder** | No server is set, so the PDF cannot be downloaded. |
| **not a Reader's credentials file** | The file chosen is not a credentials file. |
| **this file holds nothing for Reader's Scanner** | The file has no section this app can use. |

### On the computer

| Message | Meaning, and what to do |
|---|---|
| **no scanner found** (with **look again**, **get NAPS2**, **from files…**) | No scanner answers by itself and NAPS2 is not installed. The text says: **Most scanners made since 2015 (AirScan, Mopria) are found by themselves, on the network or by USB: is yours switched on? The others need NAPS2, a free program installed separately, from naps2.com. Pictures and PDFs can be brought in from files meanwhile.** |
| **no scanner found — is it switched on?** / **the scanner is not answering — is it switched on?** | **Switch the scanner on and check its cable; then scan again.** |
| **the feeder is empty** | **Put the pages in the feeder, or choose « glass ».** |
| **this scanner has no feeder** / **this scanner cannot scan both sides** | Choose another source under **from**. |
| **the scanner is busy** / **the scanner is warming up — try again in a moment** | Wait and scan again. While it waits by itself the app says **the scanner is getting ready…**. |
| **the scanner's cover is open** / **paper jam in the scanner** / **two sheets went in together** | See to the scanner, then **scan again**. |
| **the connection to the scanner was interrupted** | Check the cable or the network, then scan again. |
| **SANE is not installed (the scanner drivers)** | On Linux, NAPS2 needs SANE to reach this scanner. |
| **scan cancelled** / **the scan did not work** | The scan was stopped, or failed without a known reason. |
| **nothing could be read in these files** | The files brought in hold no usable picture. |
| **poppler-utils is needed to read a PDF** | On Linux, install poppler-utils: it is needed to bring in PDFs, and to show the pages of documents scanned elsewhere. |
| **Tesseract is not installed: the pages are kept without their text** | Install Tesseract (Linux); the PDF is made without searchable text. |
| **no reading model for français — it could not be downloaded** | The language's model is missing and could not be fetched. Check the connection, then **read the text again in**. |
| **cannot reach the server** / **wrong username or password** / **not a WebDAV folder at this address** | Shown on the sync line. Check the settings. |
| **its PDF needs the WebDAV folder** / **the PDF is not on the server (any more)** | As on the phone, for a document scanned elsewhere. |
| **an error — see errors.log** | An unexpected error was written to `errors.log` in the documents folder; the app goes on. |

After a failed scan the right side offers **scan again**, **back to the pages** (if pages are waiting) and **from files…**.


# Reader's Feeds

*Android 1.2.1*

## What it is

Reader's Feeds is a reader for RSS and Atom feeds: you give it the addresses of the sites you follow, and it shows their latest articles as one plain list, title in black, source and age in grey. An article is read inside the app as text only, cut into pages that end on a whole line, so you turn pages instead of scrolling; this is made for e-ink screens. It also reads paid Substack publications once you have signed in.

Everything is two colours, without icons, images or animation. There is no account, no server of its own and no synchronisation: the app talks only to the sites you follow.

It deliberately does not show pictures, does not mark articles as read or unread, does not notify you of new articles and does not fetch anything while it is closed.

The app is written in six languages (English, French, German, Spanish, Portuguese, Russian) and follows the language of the phone; any other language gives English.

## First start

The app asks for no permission. It only uses the internet connection.

There is no account to create and nothing to enter. One source is already in the list and enabled: **Wikipedia — Featured Articles**. On opening, the title line shows **fetching…** while the app fetches the feeds, then the list of articles appears.

If nothing has been fetched yet, the title line reads **feeds** and the page shows one of these lines:

- **nothing yet. Pull down to refresh.** when sources are enabled but no article has arrived;
- **no source enabled. ⋯ › sources.** when every source is disabled or the list of sources is empty.

To add your own sources, tap **⋯** at the top right, then **sources**.

## The screens

Every screen has a grey title line at the top. On the left, **←** goes back to the previous screen. On the right, where there is one, **⋯** opens the menu of the screen. Menus open from the bottom of the screen as a list of words; tap outside a menu to close it. Short messages from the app appear for three seconds in a band at the bottom.

### The list of articles (home)

This is the screen the app opens on. It gathers the latest articles of all enabled sources.

The title line shows the count, for example **12 articles · 3 sources**; **· …** is added at the end while a refresh is running. Tapping the title line refreshes the list.

Each article takes one row: the title (two lines at most) and, under it in grey, the name of the source, the age of the article and the word **saved** if you have saved it. The age reads **now**, then minutes (**5 min**), hours (**3 h**), days (**2 d**) and, after seven days, the date as day.month.year.

- Tap an article to read it.
- Long-press an article to open its menu: **read**, **save for later** (or **forget** if it is already saved), **open in the browser**, **share**.
- Pull the list down to refresh it (when the lists are set to **scrolling** and the list is not empty).

When the lists are set to **pages** (see Settings), the list does not scroll. Each page holds as many rows as fit; the bottom line shows **‹**, the page number such as **1 / 4**, and **›**. Tap **›** or swipe up for the next page, tap **‹** or swipe down for the previous one. In this mode there is no pull-down gesture: refresh by tapping the title line or with **⋯** › **refresh**.

The **⋯** menu holds:

- **sources**: opens the list of sources.
- **saved for later**: opens the saved articles.
- **refresh**: fetches all enabled sources again.
- **order: latest first** or **order: one per source**: the entry shows the order in use; tap it to switch to the other one.
- **white on black** or **black on white**: switches the colours of the whole app to the one named.
- **settings**: opens the settings.

The two orders:

- **order: latest first**: the most recent article first, all sources mixed. A source never takes more than two rows in a row: its third consecutive article is pushed a little further down.
- **order: one per source**: the most recent article of each source, then the second of each source, and so on. The sources come in the order of their most recent article.

The app always starts in **order: latest first**.

The list is refreshed when the app opens, and when you come back to the app after more than five minutes. At most 20 articles are taken from each source. An article that appears in two sources is shown once.

### The article (reader)

The title line shows the name of the source. While the text is being prepared the page reads **fetching the text…**.

The first page starts with the title of the article and a thin line; the text follows. The bottom line shows the page number, for example **3 / 12**, with **‹** and **›** when there is a page before or after.

- Tap the right half of the screen for the next page, the left half for the previous page.
- Swipe to the left for the next page, to the right for the previous page.

The text comes from the feed when the feed carries the full article; otherwise the app loads the article's web page and keeps its text. Pictures, videos, captions, menus and comments are left out.

If the text cannot be obtained, the page shows **the text could not be extracted** and, under it, **open in the browser**, which opens the article in your browser.

The **⋯** menu, headed by the title of the article, holds:

- **save for later** (or **forget** if it is already saved);
- **open in the browser**: opens the article's web page in your browser;
- **share**: hands the title and the address of the article to another app;
- **larger text** and **smaller text**: one step at a time; the pages are cut again and you stay at about the same place;
- **serif** or **sans-serif**: switches to the font named;
- **white on black** or **black on white**: switches to the colours named.

### Saved for later

Opened with **⋯** › **saved for later** from the home list. It shows the articles you saved, the most recently saved first. Under each title: the source, how long ago you saved it, and **saved**.

Tap to read, long-press for the same menu as in the home list (**read**, **forget**, **open in the browser**, **share**). **forget** removes the article from this list.

A saved article stays 90 days, then leaves the list by itself. When the list is empty it reads **nothing saved. Long-press an article to keep it here for 90 days.**

### Sources

Opened with **⋯** › **sources** from the home list. Each source takes one row:

- a box on the left: **■** enabled, **□** disabled. Tap the box to enable or disable the source. A disabled source is written in grey and is no longer fetched;
- the name of the source. Tap it to see the articles of this source alone;
- under the name, in grey: **signed in** for a paid Substack that holds a sign-in, **no answer** if the source is enabled but gave no article at the last refresh, then the site of the feed.

Long-press a source for its menu, headed by its name:

- **disable** or **enable**;
- **articles**: the articles of this source alone;
- **sign in again**: only for a source that is signed in; opens the Substack sign-in to replace the sign-in kept;
- **forget the sign-in**: only for a source that is signed in; erases the sign-in and keeps the source;
- **remove**: deletes the source from the list at once, without asking.

At the bottom of the screen, **+ add a feed** adds a source.

The **⋯** menu holds:

- **add a feed**
- **add a paid Substack**
- **import OPML**
- **export OPML**
- **import Substacks (CSV)**
- **export Substacks (CSV)**

When the list is empty it reads **no source yet. ⋯ › add a feed, or import an OPML file.**

Sources stay in the order in which they were added.

### The articles of one source

Opened by tapping the name of a source, or with **articles** in its menu. The title line shows the name of the source, followed by **· …** while it is being fetched. The list works like the home list, without the name of the source under each title. It also works for a disabled source.

If the feed returns nothing, the page reads **nothing came back from this feed.**

### Substack sign-in

Opened by **add a paid Substack** and by **sign in again**. The screen shows the Substack sign-in web page inside the app, under the title **Substack sign-in**. Sign in there as you would in a browser.

If the app can pick up the sign-in from the page, the screen closes by itself. If it does not, tap **paste** at the top right: a box opens with the text **if signing in here does not work: in a computer's browser, signed in to Substack, open DevTools › Application › Cookies › substack.sid and paste its value here.** Paste the value and tap **save**.

**←** leaves the screen without signing in; nothing is added or changed.

### Settings

Opened with **⋯** › **settings** from the home list. See the Settings section below for each row.

## How to

### Read an article

1. In the list, tap the title.
2. Tap the right half of the screen to go forward, the left half to go back.
3. Tap **←** to return to the list.

### Refresh the list

Use any of these: tap the title line of the home list; open **⋯** and tap **refresh**; or pull the list down (lists set to **scrolling**, list not empty).

### Change the order of the list

1. On the home list, tap **⋯**.
2. Tap **order: latest first** to switch to one article per source in turn, or **order: one per source** to return to the most recent first.

### Save an article for later

1. Long-press the article in a list, or open it and tap **⋯**.
2. Tap **save for later**.

The word **saved** appears under its title. To find it again: home list, **⋯** › **saved for later**.

### Take an article out of the saved ones

1. Long-press the article (in any list), or open it and tap **⋯**.
2. Tap **forget**.

### Open an article in the browser

Long-press the article, or open it and tap **⋯**, then tap **open in the browser**.

### Share an article

1. Long-press the article, or open it and tap **⋯**.
2. Tap **share**.
3. Choose the app to send it with. The title and the address of the article are sent.

### Add a feed

1. Home list, **⋯** › **sources**.
2. Tap **+ add a feed** at the bottom (or **⋯** › **add a feed**).
3. Under **address of the feed (or of the site)**, type the full address of the feed, starting with `https://`, and tap **ok**.
4. Under **name**, keep the name proposed (the site's name) or type your own, and tap **ok**.
5. Go back to the home list and refresh it to see the articles.

The address must be that of the RSS or Atom feed itself. Only for an address at substack.com does the app complete the address of the site into the address of its feed. The app does not check the address when you add it: if it is wrong, the source will show **no answer** after the next refresh.

### Follow a free Substack publication

Add it as a feed (see above) with the address of the publication, for example `https://example.substack.com`. The app adds the feed's ending itself.

### Add a paid Substack

1. Home list, **⋯** › **sources**, then **⋯** › **add a paid Substack**.
2. Under **address of the publication**, type the address, for example `https://example.substack.com`, without a slash at the end, and tap **ok**.
3. On the **Substack sign-in** screen, sign in to your Substack account.
4. If the screen does not close by itself once you are signed in, tap **paste**, paste the value described in the box and tap **save**.

The publication appears in the sources with **signed in** under its name. Its name is taken from its address.

### Sign in again to a Substack, or forget the sign-in

1. In **sources**, long-press the publication.
2. Tap **sign in again** to sign in anew, or **forget the sign-in** to erase the sign-in from the phone.

### Disable or enable a source

In **sources**, tap the box in front of its name (**■** enabled, **□** disabled), or long-press the source and tap **disable** or **enable**. Refresh the home list afterwards.

### See the articles of one source only

In **sources**, tap the name of the source.

### Remove a source

1. In **sources**, long-press the source.
2. Tap **remove**. The source is deleted at once.

### Move your list of sources to another device

On the first device:

1. **sources**, **⋯** › **export OPML**.
2. Choose where to send the file `readers_feeds.opml` (a message to yourself, a cloud folder, a file manager).

On the other device:

1. Get the file onto the device.
2. **sources**, **⋯** › **import OPML**, and pick the file.

The app answers with the number of sources, for example **12 sources added**. A source whose name is already in your list is not added a second time. Imported sources are enabled.

The same **import OPML** takes an OPML file exported from another feed reader.

### Move your Substack sign-ins to another device

Two ways lead to the same result.

With the credentials file:

1. On the first device: **settings** › **export credentials**, and send the file `readers-credentials-feeds.json` to yourself.
2. On the other device: **settings** › **import credentials**, and pick the file. The app answers, for example, **2 Substack sign-ins imported**.

A publication already in the list receives the sign-in from the file; one that is missing is added.

With the CSV:

1. On the first device: **sources**, **⋯** › **export Substacks (CSV)**, and send the file `readers_feeds_substacks.csv` to yourself.
2. On the other device: **sources**, **⋯** › **import Substacks (CSV)**, and pick the file. The app answers, for example, **2 Substacks added**.

The CSV only adds publications that are missing; it does not change the sign-in of one already in the list.

Both files contain your sign-ins: anyone who has the file can read your paid publications. Keep them private and delete them once used.

### Change the size of the text

- While reading: **⋯** › **larger text** or **smaller text**.
- In **settings**: tap the row showing the size to enlarge it, long-press it to reduce it. **back to the automatic size** returns to the size chosen from the screen.

### Change the font

While reading: **⋯** › **serif** or **sans-serif**. Or in **settings**, tap the row **reading font**.

### Switch to white on black

On the home list or while reading: **⋯** › **white on black**. To come back: **⋯** › **black on white**. Or in **settings**, tap the row **colours**.

### Make the lists turn pages instead of scrolling

In **settings**, tap the row **scrolling**: it becomes **pages**.

### Put the latest titles on the home screen

1. Long-press an empty spot of your phone's home screen and open the widgets.
2. Find **Reader's Feeds** (described as **Latest articles from your RSS feeds**) and place it.

## Settings

Each row shows the value in use, with its name in grey under it. Tap a row to change it.

| Row (grey line under it) | What it changes | Choices | Default |
|---|---|---|---|
| **colours** | The colours of the whole app | **black on white**, **white on black** | **black on white** |
| **text size — tap for larger, long-press for smaller** | The size of the reading text; titles, menus and small lines follow it. Tap for one step larger, long-press for one step smaller | 13 to 30 | automatic, shown as the size followed by **· auto** |
| **back to the automatic size** (**from the screen size**) | Drops your own size and returns to the automatic one | — | — |
| **reading font** | The font of the text, in the reader and in the rest of the app | **sans-serif**, **serif** | **sans-serif** |
| **lists — pages suit e-ink screens** | Whether the lists of articles scroll or turn pages (home list, articles of one source, saved articles) | **scrolling**, **pages** | **scrolling** |
| **export credentials** (**a file to set up another device — it holds your Substack sign-ins**) | Creates the credentials file and opens the share sheet | — | — |
| **import credentials** (**Substack sign-ins from a credentials file**) | Lets you pick a credentials file and takes its Substack sign-ins | — | — |

The automatic size depends on the width of the screen: between 17 and 24, larger on a larger screen.

The last two rows are information: **Reader's Feeds**, **a black-and-white RSS reader, born from Pluralis. GPL-3.0.** and **Pierre Gallaz · developed with Claude Code**.

The order of the home list (**order: latest first** / **order: one per source**) is not a setting: it is chosen in the menu of the home list and returns to **order: latest first** each time the app starts.

## Your data

Everything stays on the phone: the list of sources and whether each is enabled, your Substack sign-ins, the saved articles (their title, address and source, not their text) and the settings.

The articles themselves are not kept: the list is fetched anew each time the app opens, and the text of an article is fetched when you open it. Without a connection there is nothing to read.

What goes over the network:

- at each refresh, a request to the feed address of every enabled source;
- when you open an article whose text is not carried by the feed, a request to the article's web page;
- for a paid Substack, your sign-in is sent with the request to that publication's feed, and to nothing else;
- the Substack sign-in screen loads Substack's own sign-in page.

Nothing is sent to the author of the app or to any other service. There is no synchronisation between devices, so there are no conflicts; a list of sources travels only by the files you export and import yourself.

Export and import:

- **export OPML** creates `readers_feeds.opml` with all your sources, enabled or not (name, feed address, site address). It holds no sign-in.
- **export Substacks (CSV)** creates `readers_feeds_substacks.csv` with the signed-in publications: name, address, feed address and sign-in.
- **export credentials** creates `readers-credentials-feeds.json`, the Reader's credentials file, with the same signed-in publications and their sign-ins. When importing, the app only reads its own part of such a file, so a credentials file that also holds the accounts of other Reader's apps can be used.

Exported files are handed to the Android share sheet; the app does not write them to a folder of its own choosing. The copy of the credentials file that the app prepares for sharing is erased the next time the app starts or exports.

Saved articles are not part of any export.

Uninstalling the app removes everything: sources, sign-ins, saved articles and settings.

## With the other apps

### Home-screen widget

The app offers one widget, **Latest articles from your RSS feeds**. It can be resized in both directions.

- The top line shows **feeds** and **open ›**: tap it to open the app.
- Under it, the latest titles (ten at most), with the source under each. The list scrolls.
- Tap a title to open the article in your browser.
- When there is nothing to show, it reads **nothing yet**.

The widget shows what the app last fetched, in the **latest first** order: it is updated each time the app refreshes its list, and does not fetch anything by itself. It is always black on white, whatever the colours chosen in the app.

### Sharing

**share** sends the title and the address of an article to any app that accepts text. **open in the browser** hands the address to your browser. The export entries hand a file to the app you choose.

The app does not appear in the share sheet of other apps and does not open links or files sent from other apps; OPML, CSV and credentials files are picked from inside the app.

## Limits

- Text only: no pictures, no videos, no links you can tap inside an article.
- No mark for read or unread articles, no search, no folders or categories for sources.
- No notification and no fetching in the background; the list is refreshed when the app is opened or when you ask.
- Nothing is kept for reading without a connection, not even the saved articles: saving keeps the title and the address, and the text is fetched again when you open it.
- A saved article is fetched from its web page without your Substack sign-in.
- At most 20 articles per source.
- When the text comes from the feed, it is cut at 50,000 characters and ends with **…**.
- A source that takes more than 10 seconds to answer is skipped for that refresh; an article page that takes more than 15 seconds gives **the text could not be extracted**.
- **add a feed** needs the address of the feed itself; it does not look for the feed on a site's page, except for addresses at substack.com.
- A source cannot be renamed or moved in the list; remove it and add it again.
- **remove** has no confirmation and no undo.
- Paid publications are supported for Substack only.
- The text size goes from 13 to 30.
- No version for the computer.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **fetching…** | The first refresh is running. Wait. |
| **nothing yet. Pull down to refresh.** | No article has arrived. Tap the title line or **⋯** › **refresh**; check your connection and the sources. |
| **no source enabled. ⋯ › sources.** | Every source is disabled, or there is none. Open **⋯** › **sources** and enable or add one. |
| **nothing could be fetched. Pull down to try again, or check the sources.** | The refresh failed. Check the connection, then tap the title line or **⋯** › **refresh**. |
| **no answer** (under a source) | The source is enabled but gave no article at the last refresh: wrong address, site out of reach, or a feed that is not RSS or Atom. It also shows on a source just added or enabled until the next refresh. |
| **signed in** (under a source) | A Substack sign-in is kept for this source. |
| **nothing came back from this feed.** | The feed of this source returned no article. Check its address; for a paid Substack, try **sign in again**. |
| **no source yet. ⋯ › add a feed, or import an OPML file.** | The list of sources is empty. |
| **fetching the text…** | The article is being loaded. |
| **the text could not be extracted** | The web page did not answer, or no article text was found in it. Tap **open in the browser** under the message. |
| **nothing saved. Long-press an article to keep it here for 90 days.** | You have no saved article. |
| **12 sources added** | The OPML file held this many sources. Those whose name was already in your list were not added again. |
| **no source in this file** | The file picked with **import OPML** holds no feed. |
| **2 Substacks added** | The CSV held this many publications. Those already in your list were left as they were. |
| **no Substack in this file** | The file picked with **import Substacks (CSV)** holds no usable line. Each line needs four values: name, address, feed address, sign-in. |
| **no paid Substack to export** | No source is signed in, so **export Substacks (CSV)** and **export credentials** have nothing to write. |
| **2 Substack sign-ins imported** | The credentials file was read and its sign-ins are in place. |
| **not a Reader's credentials file** | The file picked with **import credentials** is not a Reader's credentials file. |
| **this file holds nothing for Reader's Feeds** | The file is a Reader's credentials file but holds no Substack sign-in for this app. |
| **could not read this file** | The file could not be opened or is not in the expected format. |

Other situations:

- A paid Substack no longer gives its articles in full: renew the sign-in. In **sources**, long-press the publication and tap **sign in again**.
- A new source shows no article on the home list: go back to the home list and refresh.
- The home list is empty and pulling down does nothing: tap the title line, or **⋯** › **refresh**.
- An article shows menus or unrelated text, or misses a part: the text is taken from the web page as well as the app can; use **open in the browser** for the original.


# Reader's Detox

*Android 1.7.2*

## What it is

Reader's Detox keeps the social networks out of your phone: YouTube, Instagram, TikTok, Reddit, X and Substack, in their apps as well as in the browser. You choose the sites, optionally the hours of the day when they may open, and you start the blocking.

It works by filtering names. Each time an app wants to reach a site, the phone first looks up the site's name to find its address. Reader's Detox sets itself up as a VPN that stays inside the phone and receives only these name lookups. For a chosen site it answers "no address", so the site cannot load. Every other lookup is passed on untouched, and the rest of your traffic (pages, videos, messages) never goes through the app at all.

It is a detox you impose on yourself, not a parental lock: there is no password and no account, and you can lift the blocking whenever you want. What it adds is friction: the sites, the hours and the maths switch are locked while blocking is on, and you can ask the app to make you solve five maths problems before it stops.

The app is black and white, text only, and speaks English, French, German, Spanish, Portuguese and Russian (it follows the phone's language).

## First start

The app opens directly on its main screen. Nothing is blocked yet: the top of the screen reads **not blocking**, **every site opens normally**. All six sites are already marked **blocked**, there are no allowed hours (**none — blocked all day**) and the maths problems are **off**.

No account, no server, nothing to type.

The app asks for the following, in this order:

1. **Notifications** (Android 13 and later), when the app opens. While blocking is on, the app must show a permanent notification, **Reader's Detox is blocking**; this permission lets it appear.
2. **The VPN connection request**, the first time you tap **start blocking**. This is Android's own dialog. It must be accepted: the VPN is the mechanism that lets the app receive the phone's name lookups. If you refuse, nothing starts. Android asks only once.
3. **Running in the background**, right after blocking starts. Android asks whether the app may ignore battery optimisation, so that the system never stops the blocking to save power. The request comes back at each start as long as you have not allowed it.
4. **The always-on VPN advice**, once, after the first start. A sheet reads: **For the strongest protection, make Reader's Detox the always-on VPN: Settings › Network › VPN › Reader's Detox › Always-on VPN.** Tap **open VPN settings** to go to Android's VPN settings, or **later** to close the sheet. You can find the same shortcut afterwards in **settings**.

## The screens

### Main screen (detox)

The title **detox** is at the top left, the **⋯** menu at the top right.

**The state.** A large line reads **blocking** or **not blocking**. While blocking, this block is shown in inverted colours. The small line under it gives the detail:

| Detail | Meaning |
|---|---|
| **every site opens normally** | Blocking is off. |
| **YouTube, Instagram… blocked all day** | Blocking is on, no allowed hours: the named sites never open. |
| **YouTube, Instagram… blocked outside 6–8, 18–22** | Blocking is on and you are outside the allowed hours: the sites are blocked now. |
| **inside the allowed hours: open now, blocked again at 8:00** | Blocking is on, but the clock is inside one of your allowed hours: the sites open until the hour shown. |
| **no site chosen: nothing to block** | Blocking is on, but every site is set to **open**. |

**The sites.** Under the heading **sites**, six lines: **YouTube**, **Instagram**, **TikTok**, **Reddit**, **X**, **Substack**. Each shows **blocked** or **open** on the right. Tap a line to switch it. While blocking, the heading becomes **locked while blocking, except Substack**: the first five lines are dimmed and no longer react; only **Substack** can still be switched, and the change applies at once.

**The allowed hours.** A line shows your ranges in short form, for instance **6–8, 18–22**, or **none — blocked all day**, with the caption **allowed hours**. Tap it to open the *allowed hours* screen. While blocking, the caption reads **allowed hours · locked while blocking** and the line no longer reacts.

**The maths problems.** A line shows **on** or **off** with the caption **5 maths problems before stopping**. Tap it to switch. While blocking, the caption reads **5 maths problems before stopping · locked while blocking** and the line no longer reacts, so you cannot remove the obstacle once it is in place.

**The action line**, at the very bottom, starts or stops the blocking. It reads:

- **start blocking** when blocking is off;
- **stop blocking** when blocking is on and the maths problems are off: one tap stops it;
- **stop blocking — 5 problems first** when blocking is on and the maths problems are on: one tap opens the problems screen.

**The ⋯ menu** opens a sheet at the bottom of the screen. Tap outside it, or press back, to close it. Its entries:

- the same action as the bottom line (**start blocking**, **stop blocking** or **stop blocking — 5 problems first**);
- **allowed hours** (only when blocking is off): opens the *allowed hours* screen;
- **black on white** or **white on black**: switches to the colours named;
- **settings**: opens the settings screen.

### Allowed hours

The title **← allowed hours** is at the top; tap it (or press back) to return.

A note explains the rule: **The chosen sites open during these hours and are blocked the rest of the day. With no hours, they are blocked all day. A range ending earlier than it starts runs past midnight.**

Below it, one line per range, for instance **6:00 – 8:00**. A range that crosses midnight, such as **22:00 – 6:00**, carries the mention **over midnight**. With no range, the screen reads **none — blocked all day**.

- Tap a range to open a small menu with **change** and **delete**.
- Tap **+ allowed hours**, at the bottom, to add a range.

Adding or changing a range asks two questions, one after the other, each with a number keyboard and the buttons **cancel** and **ok**: **open from which hour? (0–23)**, then **from 6:00 until which hour? (0–23)** (with the hour you just gave). When you change a range, the old hour is already written and selected: type to replace it, or just confirm.

Ranges are in whole hours, from 0 to 23. The sites open from the first hour and are blocked again from the second: **6:00 – 8:00** means open from 6:00 until 8:00. The list is kept sorted by starting hour, and a range entered twice is kept once.

If blocking is on while this screen is displayed, the ranges are dimmed and **locked while blocking** replaces **+ allowed hours**.

### Stop blocking (the maths problems)

This screen appears when you ask to stop while **5 maths problems before stopping** is **on**. The title is **← stop blocking**.

It shows:

- the explanation **Five problems, each harder than the last. Solve all five to stop blocking.**;
- where you are, for instance **question 1 of 5 · easy**, and a progress line;
- the problem;
- the answer field, marked **your answer**, with a number keyboard;
- **±**, to the right of the field: tap it to put or remove a minus sign in front of your answer (some answers are negative, and not every number keyboard has a minus key);
- **check**, at the bottom, to submit your answer (the keyboard's confirm key does the same).

The five levels are **easy**, **medium**, **hard**, **very hard** and **expert**. The problems are drawn at random each time:

| Level | Kind of problem |
|---|---|
| **easy** | An addition and a multiplication, such as 47 + 23 × 6 = ? |
| **medium** | A percentage (**What is 35% of 240?**) or a product minus a square |
| **hard** | A power minus a number, or an equation (**Solve for x: 7x + 12 = 61**) |
| **very hard** | The larger root of a quadratic equation, a square root plus a number, or two equations (**If x + y = 30 and x − y = 8, what is x?**) |
| **expert** | The sum of an arithmetic series, a remainder (**What is 9³ mod 11?**), a count of arrangements, or the sum of both roots of a quadratic equation |

After a right answer the screen shows **correct** and moves to the next problem. After the fifth, blocking stops and you return to the main screen.

After a wrong answer the screen shows **wrong answer, try again** and empties the field; you may try as often as you like. From the second wrong answer on the same problem, a line **hint: …** appears with a pointer to the method.

You can type a decimal with a point or a comma.

Leaving this screen (tap the title or press back) gives up: blocking stays on, and next time you start again from question 1 with new problems.

### Settings

Opened from **⋯** then **settings**. The title **← settings** takes you back. Each line shows the current value in large type and its name under it; a tap changes it. See the *Settings* section for the details.

At the bottom, two lines of information: **Reader's Detox**, **blocks social networks on this phone**, and **Pierre Gallaz · developed with Claude Code**. They do nothing when tapped.

### The notification

While blocking is on, a permanent notification reads **Reader's Detox is blocking**, **social networks blocked**. It stays during the allowed hours too, because the app keeps running then and simply lets the sites through. Tap it to open the app. It cannot be swiped away; it disappears when blocking stops. In Android's notification settings its category is called **blocking**.

## How to

### Start blocking

1. On the main screen, check under **sites** that each site you want out reads **blocked**; tap a line to switch it.
2. Tap **start blocking** at the bottom.
3. The first time, accept Android's VPN connection request.
4. If Android asks whether the app may run in the background, allow it.

The top of the screen turns to **blocking**, in inverted colours, and the notification **Reader's Detox is blocking** appears.

### Choose which sites are blocked

1. Blocking must be off (stop it first if needed).
2. Under **sites**, tap a site to switch it between **blocked** and **open**.

Substack is the exception: you can switch it at any time, even while blocking.

### Let the sites open at certain hours

1. Blocking must be off.
2. Tap the **allowed hours** line (or **⋯**, then **allowed hours**).
3. Tap **+ allowed hours**.
4. To **open from which hour? (0–23)**, type the starting hour, for instance 18, then **ok**.
5. To **from 18:00 until which hour? (0–23)**, type the ending hour, for instance 22, then **ok**.
6. Repeat for another range if you want several in the day.
7. Go back and tap **start blocking**.

The sites then open from 18:00 to 22:00 and are blocked the rest of the day. Blocking stays "on" all the time; the app lets the sites through during the allowed hours by itself.

### Set a range that crosses midnight

Give an ending hour smaller than the starting hour: from 22 until 6 gives **22:00 – 6:00**, marked **over midnight**. The sites open from 22:00 in the evening until 6:00 in the morning.

### Change or delete a range

1. Blocking must be off.
2. Open **allowed hours**.
3. Tap the range.
4. Tap **change** and answer the two questions again, or tap **delete**.

### Block all day

Delete every range in **allowed hours**. The line reads **none — blocked all day**.

### Make stopping harder

1. Blocking must be off.
2. On the main screen, tap the line captioned **5 maths problems before stopping** so that it reads **on**.
3. Tap **start blocking**.

From now on the bottom line reads **stop blocking — 5 problems first**, and the switch itself is locked until blocking has stopped.

### Stop blocking

Without the maths problems: tap **stop blocking**. It stops at once.

With the maths problems:

1. Tap **stop blocking — 5 problems first**.
2. Type the answer to each problem and tap **check**.
3. After the fifth right answer, blocking stops.

### Change the sites, the hours or the maths switch while blocking

You cannot, apart from Substack. Stop blocking first, make your change, then start again.

### Keep the blocking alive after a restart of the phone

The app starts the blocking again by itself after the phone restarts and after an update of the app, if blocking was on. For the firmest hold:

1. Open **⋯**, then **settings**.
2. Tap **always-on VPN**: Android's VPN settings open. Choose Reader's Detox there and turn on Android's always-on VPN option.
3. Back in **settings**, tap **allow running in the background** and accept. The line then reads **runs in the background: allowed**.

### Switch between black on white and white on black

Open **⋯** and tap **black on white** or **white on black** (the menu names the colours you will get). The same switch is in **settings**, on the **colours** line.

### Start or stop from the home screen

Add the Reader's Detox widget to your home screen (see *With the other apps*) and tap its switch.

## Settings

Open **⋯**, then **settings**.

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **always-on VPN** (**so the blocking survives reboots**) | Opens Android's VPN settings, where you can make Reader's Detox the always-on VPN. | — | — |
| **allow running in the background** (**so Android never stops the blocking**) | Asks Android to exempt the app from battery optimisation. Once granted, the line reads **runs in the background: allowed**. | — | not allowed |
| **colours** | The colours of the app and of its widget. | **white on black**, **black on white** | **white on black** |
| **text size** | The size of the text in the app. Each tap moves to the next size. | **small**, **medium**, **large** | **medium** |
| **font** | The typeface of the app. Each tap moves to the next one. | **sans-serif**, **serif**, **mono** | **sans-serif** |
| **haptic tick** | A short vibration when you switch a site, the maths problems, or start and stop. | **on**, **off** | **on** |

The settings that decide what is blocked are on the main screen:

| Setting | Choices | Default |
|---|---|---|
| **YouTube**, **Instagram**, **TikTok**, **Reddit**, **X**, **Substack** | **blocked**, **open** | **blocked** for all six |
| **allowed hours** | any number of ranges in whole hours | **none — blocked all day** |
| **5 maths problems before stopping** | **on**, **off** | **off** |

## Your data

**On the phone only.** The app stores your choices (sites, allowed hours, maths switch, whether blocking is on, colours, text size, font, haptic tick) in its private storage on the phone. There is no account and no synchronisation. The app keeps no history of the sites you visit or of the names looked up.

**What goes over the network.** Reader's Detox has no server of its own and sends nothing to its author. Here is exactly what it does while blocking is on:

- Only the phone's name lookups reach the app. Everything else (the pages, the videos, your messages) leaves the phone the usual way, without passing through the app.
- A lookup for a blocked site, outside the allowed hours, is answered by the app itself, on the phone. It goes nowhere.
- Every other lookup is passed on, unchanged, to the name servers of the network you are connected to (your Wi-Fi or your mobile operator), the same ones the phone would use without the app.
- If those servers do not answer, the app asks Quad9 instead, a Swiss non-profit name service (9.9.9.9), so that the phone keeps working. In that case, and only then, Quad9 receives the names being looked up. The network's own servers stay the first choice: while they are silent the app asks Quad9 directly, tries them again every minute, and returns to them as soon as they answer or you change network.

**Mobile networks.** The app also works on mobile networks that use IPv6 only.

**Backup, export, import.** There is none. The app's data is excluded from Android's backups. On a new phone you set your sites and hours again.

**Uninstalling** removes everything, and of course ends the blocking.

## With the other apps

### Home-screen widget

The app offers one widget, described in the widget list as **blocking on or off; stopping asks the maths problems when they are on**. It can be resized.

On the left it shows the state in words:

| First line | Second line |
|---|---|
| **not blocking** | **every site opens normally** |
| **blocking** | **blocked all day** (no allowed hours) |
| **blocking** | **allowed hours: open until 8:00** (inside a range) |
| **blocking** | **blocked until 18:00** (outside the ranges; the hour is when the next range opens) |

On the right, a switch reads **on** (filled) or **off** (outlined).

- Tap the text to open the app.
- Tap the switch when it reads **off**: blocking starts at once. If Android's VPN connection request has not been accepted yet, the app opens on that request instead.
- Tap the switch when it reads **on**: blocking stops at once, or, if **5 maths problems before stopping** is on, the app opens on the problems. The widget is no shortcut around them.

The widget follows the **colours** setting of the app. Its text is refreshed at every change of state and every hour while allowed hours are set.

### Other apps

Reader's Detox has no link with the other Reader's apps, receives nothing shared from other apps and opens no files. It can be installed beside the original SocialBlocker app.

## Limits

- **Six sites, no more.** You cannot add a site of your own. The list of names behind each site is fixed in the app.
- **What each site covers.** YouTube: youtube.com, youtu.be, youtube-nocookie.com, YouTube Kids, YouTube Music and the addresses that serve its images and videos. Instagram: instagram.com, ig.me and its image servers. TikTok: tiktok.com, musical.ly and its video servers. Reddit: reddit.com, redd.it and its image servers. X: x.com, twitter.com, their image servers, and t.co (so shortened links from X do not open either). Substack: substack.com and its own servers; a newsletter published under its own address is not covered.
- **Whole hours only.** A range runs from one full hour to another; no minutes, and the same ranges apply every day of the week.
- **One VPN at a time.** Android allows a single active VPN. While Reader's Detox is blocking, you cannot use another VPN; starting another one stops the blocking.
- **Not a lock.** You can always stop it. Turning the VPN off in Android's settings, or starting another VPN, also stops the blocking, without the maths problems. For a child's phone, use the original SocialBlocker, which has a password.
- **Name lookups only.** The app filters the lookups the phone sends to its usual name server. An app that finds addresses by its own means (for instance a browser whose "secure DNS" option is on) is not filtered.
- **No per-day statistics, no history, no timer.** The app does not count the time you spend or the attempts blocked.
- **Android 7.0 or later.**

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **locked while blocking, except Substack** | Shown above the sites while blocking. Stop blocking to change the other five. |
| **locked while blocking** | Shown beside **allowed hours** and **5 maths problems before stopping**, and at the bottom of the allowed hours screen. Stop blocking to change them. |
| **no site chosen: nothing to block** | Blocking is on but every site is **open**. Stop, set at least one site to **blocked**, start again (Substack can be switched without stopping). |
| **inside the allowed hours: open now, blocked again at 8:00** | Not a fault: the clock is inside one of your allowed hours. |
| **(0–23)** added after the question | The hour you typed was not accepted. Type a whole number from 0 to 23. The ending hour must also differ from the starting hour. |
| **a number, please** | On the problems screen: what you typed is not a number. |
| **wrong answer, try again** | The answer is not right. The field is emptied; try again. A **hint: …** appears from the second miss. |
| **correct** | The answer is right; the next problem follows. |

**A site still opens while the app says blocking.** Check the detail line: you may be inside the allowed hours, or the site may be set to **open**. Otherwise, see *Name lookups only* under *Limits*.

**The app says not blocking although you did not stop it.** The VPN was turned off in Android's settings, or another VPN app took its place: both count as stopping. Tap **start blocking** again; Android may ask for the VPN connection request once more.

**Blocking does not come back after a restart.** Open **settings**, tap **allow running in the background**, and follow **always-on VPN** to make Reader's Detox the always-on VPN.

**Nothing happens when you tap start blocking.** Android's VPN connection request was refused. Tap **start blocking** again and accept it.

**No notification appears.** The notification permission was refused. To see the notification, allow notifications for Reader's Detox in Android's settings.

**The answer is negative and the keyboard has no minus key.** Type the number and tap **±**.


# Reader's Files

*Android 1.0.0*

## What it is

Reader's Files is a file manager for Android. It opens on a page of plain words (**Downloads**, **Videos**, **Images**, **Audio**, **Documents**, **Apps**, **Archives**, then your storages with the space left on each) and shows everything in black and white, whatever your wallpaper.

It browses folders in tabs, copies, moves, renames, deletes and compresses files, searches by name or inside text files, lists the installed apps, and has its own viewers for pictures, video, audio, PDF and text. ZIP files are browsed like folders; 7z, rar, tar and many other archives are unpacked into a folder beside them.

It is a modified version of Prism File Explorer, and beyond the home page most screens are still the original Prism ones. It asks for no network access: it never connects to the Internet, has no cloud storage, no FTP, no network shares, and does not check for updates by itself (updates come from F-Droid or Reader's Installer).

The app follows the language of the phone: English, French, German, Spanish, Portuguese (Brazil), Russian, Polish, Turkish, Chinese and Persian. A few labels exist only in English; they are written in quotation marks in this chapter.

## First start

At the first start the app shows a screen titled **Storage Access Required** with the text "To manage your files, we need access to your device storage. This allows you to save, organize, and access your content seamlessly." and two buttons:

- **Grant Access**: on Android 11 and later this opens the Android page "All files access" for Reader's Files; switch it on and come back. On Android 8 to 10 the usual Android permission question appears instead.
- **Close**: leaves the app. Nothing works without this access.

If you come back without having given the access, the app says **Storage access permission is required** and stays on that screen.

There is no account and no server to enter. Once the access is given you land on the **Home** tab.

Other permissions the app holds, none of which asks you a question at the first start:

- installing packages: used when you tap **Install** or **Update** on an APK file;
- seeing all installed apps: used by the **Apps** tab;
- adding shortcuts to the home screen: used by **Add to home screen**;
- running in the foreground and notifications: used while a long copy, move, deletion or compression continues in the background. The app does not ask for the notification permission itself; on Android 13 and later, allow notifications for Reader's Files in the Android settings if you want to see this notification.

## The screens

### The top bar and the tabs

At the very top:

- an icon with three lines on the left: it opens the **About** card (see "About and Logs" below), not a menu;
- the title of the current tab (**Home**, **Files**, **Apps**, or the name of a category) and, in a folder, a small line such as "folders: 3, files: 12", with " (2 selected)" when files are selected, or "empty folder";
- the three-dot menu on the right. Its entries depend on the tab:
  - in a folder: **Show hidden files** (with a check box) and **Display mode**;
  - on the home page: **Customize home tab**;
  - always: **Manage startup tabs** and **Preferences**.

Under it, the row of tabs:

- **+** adds a new **Home** tab.
- Tap a tab to show it. Swipe the page left or right to change tab. On the last tab, pulling the page further to the left also adds a new **Home** tab.
- Tap the tab that is already shown to open its menu: **Add to startup tabs** or **Remove from startup tabs**, **Close** (not offered for the first tab), **Close others**, and **Home** (replaces this tab with the home page).
- Hold a tab and drag it to change the order.
- Swipe a tab downwards to close it (the last remaining tab cannot be closed).

The name of a folder tab is the folder's name; long names are shortened.

The Back button, in order: clears a selection; goes up one folder; at the top folder of a storage, replaces the tab with the home page; on the home page of a tab other than the first, closes that tab; on the first tab, leaves the app after a second press (**Press again to exit**). Three settings under **Behavior** change this.

### Home

The home page is a list of words. In its default layout it shows, from top to bottom:

1. The categories: **Downloads** (the Download folder), **Videos**, **Images**, **Audio**, **Documents** (PDF, Word, Excel and PowerPoint files), **Apps** (the installed apps) and **Archives** (zip, rar, tar, gzip and 7z files). Each word opens in the current tab. Videos, images, audio, documents and archives are gathered from the whole storage, whatever folder they are in.
2. The storages: **Internal Storage**, any SD card or USB drive under the name Android gives it, and **Root** (the system folders of the phone). Under each name a caption reads "12 GiB free of 64 GiB" and a thin line shows how full it is.
3. **Pinned Files**, shown only when you have pinned something: tap a file to open it or a folder to enter it; hold a row to reveal a bin on its right, and tap the bin to unpin.
4. **Bookmarks**, shown only when you have bookmarks: opens the list of bookmarked files and folders.
5. **Recycle bin**: opens the folder that holds deleted files.

Two more sections are switched off by default and can be added with **Customize home tab**:

- **Recent Files**: a horizontal row of the files changed in the last 24 hours (25 at most). Tap one to open it; hold it to see it in its folder; **More** at the end opens the full list (last five days, 100 files at most). When there is nothing, the text **No Recent Files** is shown.
- **Jump to path**: opens a small window where you type a path.

### Customize Home Tab

Reached from the three-dot menu of the home page. Each section of the home page is a row with its name, a short description, a handle (two lines) and a switch:

| Section | Description shown | Default |
|---|---|---|
| **Categories** | Quick access categories | on |
| **Storage** | Storage devices and locations | on |
| **Pinned Files** | Quick access important files | on |
| **Bookmarks** | Bookmarked files and folders | on |
| **Recycle bin** | Deleted files | on |
| **Recent Files** | Recently modified files | off |
| **Jump to path** | Quick path navigation | off |

Use the switch to show or hide a section, drag the handle to change the order. The circular-arrow icon at the top right puts the default layout back. The back arrow saves. If you switch everything off, the app keeps **Categories** and **Storage**.

### Customize startup tabs

Reached from **Manage startup tabs** in the three-dot menu. It lists the tabs opened when the app starts (by default a single **Home** tab). Each row shows the kind of tab (**Home**, **Apps** or **Files** with the folder's path), a handle to reorder and a bin to remove it (at least one tab stays). The circular-arrow icon puts back the single **Home** tab. To add a tab to this list, use **Add to startup tabs** in the menu of a tab.

### A folder (the Files tab)

From top to bottom:

**The path bar.** A house icon returns to the folder this tab started from. Then every folder of the path: tap one to go there, hold one to copy its path (message **Path copied to clipboard**). In a category (Images, Videos…) the path bar is replaced by a row of filters: **ALL**, then one per folder that contains such files.

**The list.** Each row shows an icon or a thumbnail (pictures, videos, audio covers, PDF first page, app icons), the name, and a line of details: date, then for a file its size and its extension. A small padlock marks what cannot be read.

- Tap a folder to enter it, tap a file to open it.
- Hold a row to select it. While something is selected, a tap selects or deselects, and holding another row selects everything between the two.
- Hold a row that is already selected to open the options sheet.
- In list view, tapping the icon of a row selects it directly.
- Pull the list down to refresh it.
- The Back button first clears the selection, then goes up one folder.

An empty folder shows **Empty**, and, when hidden files are not shown, **Show hidden files in settings to see all files**. A folder you may not read shows **This folder is inaccessible**.

**The bottom bar.** Without a selection: **Task**, **Search**, **Create**, **Sort**, **Bookmarks**. With a selection: **Task**, **Search**, **Create**, **Select All** (tap again to deselect all), **Options**, and above them a row of five icons: bin (delete), scissors (cut), two sheets (copy), a letter A (rename), an "i" (properties). Swiping up on the bottom bar opens the bookmarks; swiping up on the row of icons opens the options sheet. **Create** is absent where nothing can be created (Root, the categories). In the recycle bin, **Task** is replaced by **Empty** and **Create** is absent.

### The options sheet

Opened by **Options**, or by holding a selected row. At the top, the name of the file (with "and 2 more" when several are selected), then a row of icons: bin (delete), scissors (cut), two sheets (copy), letter A (rename), share (only when the selection contains no folder), "i" (properties). Then, depending on what is selected:

- **Open in new tab**: one folder.
- **Open with**: one file; choose the app.
- **Add to bookmarks**, or **Remove from bookmarks** when you are in the bookmarks list.
- **Pin to home tab**. **Unpin from home tab** is offered instead only when your selection is exactly the whole set of pinned files; the simple way to unpin is on the home page.
- **Add to home screen**: one file or one folder, in a real folder (not in a category); asks your launcher to add a shortcut.
- **Edit with text editor**: one file.
- **Convert to APK**: one file ending in .apks, .xapk or .apkm.
- **Compress**: not offered inside a ZIP file.
- **Remove default opening method**: one file; forgets the app you chose as default for this kind of file.

### Tasks

Copying and moving work with tasks. **Cut** or **Copy** does not act at once: it adds a task to a list and says **New task has been added**. You then go to the destination folder, tap **Task**, and tap the task to run it there.

The **Tasks** sheet groups them under:

- **Running tasks**: tap one to bring its progress window back.
- **Paused tasks**: stopped by you, or waiting for your answer to a conflict. Tap to continue.
- **Failed tasks**: tap to try again.
- **Pending tasks**: waiting for a destination. Tap one to run it in the folder you are in. In a category or in a search list the app answers **Tasks cannot be run here**.
- **Invalid tasks**: their source files no longer exist.

Each task shows its kind (**Copy**, **Move**, **Compress**…), "Content: 3" (the number of items) and the time it was created. Hold a task to unfold the names of its files or, for a failed task, the reason. Swipe a task to the left and tap the bin to remove it. With no task the sheet says **Empty** and **No tasks available**.

While a task runs, a window shows its title, the current step and file (**Counting files…**, **Copying**, **Moving**, **Deleting source files…**, **Deleting**, **Compressing**, **Renaming**, "Extracting", **Merging**, **Signing**, **Aligning APK file**, **Updating**, **Finalizing**, **Completed**), a progress bar, a count such as "12/40" and a percentage. **Hide** lets the task go on in the background (not offered for renaming and for converting to APK); **Stop** interrupts it (the button reads **Stopping…**). A notification titled **Tasks** then reads **Tasks are running…**, or **Action required** when a task waits for you. In Android's notification settings its category is named **Task Running Notification**.

When a file with the same name already exists at the destination, a window titled **Conflict** says "File NAME already exists in destination folder." Tick **Apply to subsequent conflicts** to answer once for all, then choose **Replace**, **Skip**, or **Cancel** (the task stays under **Paused tasks**).

At the end the app says **Task completed**, **Task failed** or **Task has been paused**.

### Search

**Search** in the bottom bar opens a full page. Type in the field **Search Query** and tap the magnifier (or the search key of the keyboard). The search covers the current folder and everything under it, hidden files included; in a category it covers the listed files. While it runs, **Searching…**, a bar and the name being examined are shown; a square button stops it.

The sliders icon on the right unfolds **Advanced Options**:

| Option | What it does | Default |
|---|---|---|
| **Ignore Case** | Upper and lower case count as the same | on |
| **Use Regex** | The query is a regular expression (if it is not a valid one, it is searched as plain text) | off |
| **By Extension** | The query is compared with the extension instead of the name | off |
| **In Content** | Also looks inside text and code files (up to 50 MB each); the first matching line is shown with "Line 12" | off |
| **Max Results: 1000** | Buttons **10**, **100**, **1K**, **5k**, **10K** | 1000 |

Under "Results (n)": **Clear** empties the list; **Expand** opens the results as a tab named **Search**, where you can select and act on them like in a folder. Tap a file in the results to open it. Hold a result for **Locate** (closes the search and shows the file in its folder) and **Copy path** (message **Copied to clipboard**).

### Sort by

**Sort** opens a sheet titled **Sort by**:

- **Apply to this folder only**: on when the sheet opens. Leave it on to sort this folder alone; switch it off to change the sorting of all folders that have no sorting of their own.
- Under "Sort Method": **Name (A-Z)** (default), **Date (newer)**, **Size (smaller)**, **Type**.
- Under "Display Options": **Folders first** (default on), **Reverse** (default off).

The choice is applied when you close the sheet.

### View Configuration

**Display mode** in the three-dot menu opens a sheet titled **View Configuration**:

- **Apply to this folder only**.
- **Display mode**: **Grid View** or **List View** (default).
- **Properties**: a slider "Column Count: 1" (1 to 5) in list view, "Cell Count: 4" (3 to 8) in grid view; then **Item Size**, a slider from **Small** to **Large** in five steps (it is named **Font Size** in grid view with cropped thumbnails).
- **Display Options**: **Crop-in Thumbnails**; in grid view also **Gallery Mode** (the name is written over the picture) and **Hide names from media files** (in gallery mode, no name on pictures and videos).

The choice is applied when you close the sheet.

### Bookmarks

**Bookmarks** in the bottom bar opens the list of bookmarked files and folders. Tap a file to open it; tap a folder to open it in a new tab. Swipe a row to the left and tap the bin to remove the bookmark. Bookmarks whose file no longer exists are removed by themselves. Empty, the sheet says **Empty** and **No bookmarks available**.

### File Properties

The "i" icon opens a sheet, titled **Loading Properties…** with the text **Analyzing files…** for the first moment. For one item, **File Properties**:

- **General**: **Name**, **Location**, **Type**, **Size**, **Modified**.
- **System**: **Owner**, **Permissions** (r, w, x).
- **Analysis**: for a folder, **Contents** ("120 files, 8 folders") and its total size; for a file, **MD5** and **SHA-256**. **Calculating…** is shown meanwhile, **Error calculating** if it fails.

For several items, **Selection Properties** with a **Selection Summary**: **selected** ("5 items"), **Total Size**, **Total Contents**.

Hold any value to copy it (**Copied to clipboard**). **Close** closes the sheet.

### Open with

A sheet titled **Open with** lists the apps able to open the file. A drop-down at the top lets you present the file as another kind: its own type, "image", "Video", "Audio", "Text" or "Any". Tap an app to open the file with it. Hold an app and choose **Set as default for this type** to always use it for files with this extension.

### An APK file

Tapping an .apk file opens a sheet with the app's icon, name, package name, version, and **Installed** if it is already on the phone. Buttons:

- **Explore**: browse the inside of the APK like a ZIP file.
- **Install**, or **Update** if the app is installed: hands the file to Android's installer.
- **Properties**: unfolds two tabs. **Details**: **Version Code**, **Size**, **Minimum SDK**, **Target SDK**, and when installed **Installed Version**, **Install Date**, **Last Update**. **Permissions**: the list, or **No permissions requested**.

A file that is not a valid APK shows **Invalid APK** and only **Explore**.

### Apps

The **Apps** tab lists installed apps with name, package name, version, size and the word **System** for system apps. At the bottom: a magnifier (search by name or package name, field **Search Query**), three choices **User** (default), **System**, **ALL**, and a sort button offering **Name**, **Size**, **Install Date**, **Update Date**.

Tap an app for its sheet: version, **Debug** if it is a debug build, and **Extract**, which adds a copy task for the app's APK file. Three tabs: **Details** (**Version**, **Size**, **Category**, **Install Date**, **Last Update**), **Advanced** (**Target SDK**, **Minimum SDK**, **UID**, **Data Directory**, **APK Path**, **Debug Mode** with **Enabled** or **Disabled**), **Permissions**. **Close** closes it.

### The text editor

Text and code files open in the built-in editor (txt, log, md, csv, json, xml, ini, html, js, py, java, kt and similar).

- Top bar: back arrow, file name, undo, redo, save (the diskette shows a pencil when there are unsaved changes), and a menu.
- Under it, the path of the file, then, once you move the cursor, its position as "line:column", the number of selected characters in brackets and "search result: 2/7" during a search; "UTF-8" on the right.
- Bottom bar: a "Tab" key (indents; with a selection, hold it to unindent), the symbols `_ = { } / \ < > | ? + - *`, two arrows that move the cursor (hold: start or end of the line; with a selection, hold to choose which end the arrows move, message **Controlling left cursor** or **Controlling right cursor**), and a folder icon.
- The folder icon opens **Recent Files**: the files opened in the editor since the app started, unsaved ones marked with a leading `*`. Tap one to switch to it. Swipe one to the left and tap the bin to close it; the file being shown answers **This file is currently open**.

The menu: **Search**, **Format** (only for .json, .java, .kt and .xml files), **Word wrap**, **Read only**, **Jump to line**, and **Preferences**, a sub-menu with **Use ICU selection**, **Pin Numbers line**, **Auto symbol pair**, **Delete empty lines**, **Delete tabs**, **Auto indentation**, **Magnifier**.

**Search** shows a panel with the fields **Find** and **Replace**, the boxes **Regex** and **Case sensitive**, and the buttons **REP** (replace this match), **ALL** (replace all), **PREV**, **NEXT**.

**Jump to line** opens **Jump to position** with a field "Line:Column (e.g. 23:11)" and the button **Go**.

### The PDF viewer

Pages scroll vertically; pinch to zoom. A bar on the left edge scrolls fast and shows the page number as "3 of 20". The top bar (back arrow, file name, "i") hides when you scroll; tap the page to bring it back. "i" opens **PDF Info**: **Name**, **Page Count**, **Size**, **Path**, **Last modified**.

### The image viewer

Pinch to zoom; tap to show or hide the controls. At the top: back arrow, name, size and dimensions, and "i" for the details sheet ("Image Details": **Name**, **Size**, **Dimensions**, **Format**, **Last modified**, **Path**). At the bottom, four buttons: background behind the picture (none, white, grey, black), fitting (fit, crop, fill the width, fill the height, stretch, never enlarged), rotate by a quarter turn, and a pencil that hands the picture to another app (**Edit with…**).

### The audio player

Cross to close, loudspeaker (**Volume** slider), bars (**Equalizer**). The cover, title, artist and album (**Unknown Title**, **Unknown Artist**, **Unknown Album** when the file says nothing), a position slider with elapsed and total time, previous, play/pause, next, a speed button (0.5x, 1.0x, 1.25x, 1.5x, 2.0x in turn) and a repeat button. Playback starts when you press play.

### The video player

Tap to show or hide the controls; pinch to zoom. Top: back arrow, file name, loudspeaker. Middle: back 10 seconds, play/pause, forward 10 seconds. Bottom: position slider with elapsed and total time. The video opens with the sound off: tap the loudspeaker to hear it.

### Preferences

See "Settings" below. Each group has a title you can tap to fold it.

### About and Logs

The three-line icon at the top left (or **About** at the bottom of the preferences) opens a card with the app's name and version and three rows:

- **Github**, **View source code**: opens the project's page in your browser.
- "Prism File Explorer", **Reader's Files is a modified version of this app (GPL-3.0)**: opens Prism's page in your browser.
- **Logs**, **View application logs**: opens the list of the app's last errors, warnings and information messages (the 5 last errors, 10 last warnings, 30 last messages). Filters at the top: "All", "Errors", "Warnings", "Info". Hold an entry to copy it. The bin opens **Clear logs** ("Are you sure you want to clear all logs? This action cannot be undone."), which clears the kind currently filtered.

## How to

### Browse a storage or a folder

1. On **Home**, tap **Internal Storage** (or your SD card, or a category).
2. Tap folders to go down. Use the Back button or tap a folder in the path bar to go up.
3. The house icon of the path bar returns to where the tab started. To return to the home page, press Back at the top folder, or tap the tab's name and choose **Home**.

### Open a file

Tap it. Pictures, videos, audio, PDF and text files open in the built-in viewers; ZIP files open like folders; other archives are unpacked; APK files show their sheet; anything else is handed to another app. To choose the app yourself, hold the file, tap **Options**, then **Open with**.

### Always open a kind of file with the same app

1. Hold the file, tap **Options**, then **Open with**.
2. Hold the app you want and tap **Set as default for this type**.

To undo it: **Options**, then **Remove default opening method**.

### Select several files

Hold the first one, then tap the others; or hold the first and then hold the last to take everything in between. **Select All** takes the whole folder. Back clears the selection.

### Copy or move files

1. Select the files.
2. Tap the two-sheets icon (copy) or the scissors (move). The app says **New task has been added**.
3. Go to the destination folder (it must be another folder than the one the files are in).
4. Tap **Task**, then tap the task under **Pending tasks**.
5. If a file already exists there, answer the **Conflict** window with **Replace** or **Skip**.

You can prepare several tasks and run each where you want. A task can be run once.

### Create a folder or an empty file

1. Tap **Create**. The window **New Content** opens.
2. Type the name. Tick **Create and open** to enter the new folder at once.
3. Tap **Folder** or **File**.

The characters `: / * ? " < > |` are not accepted.

### Rename a file

1. Select it and tap the letter A.
2. Change the name and tap **Rename**.

### Rename several files at once

1. Select them and tap the letter A. The page **Batch Rename** opens.
2. In **New Name**, write the pattern. It starts as `{p}{e}` (same name, same extension). The buttons under the field insert the pieces: **Name** `{p}`, **Extension** `{s}`, **Extension with a dot** `{e}`, **Last modified** `{t}` (as year-month-day_hour-minute-second), **Number increment** `{n}` and **Zero-padded number increment** `{zn}`. For the two numbers, replace `n` with the number to start from: `{1}` gives 1, 2, 3…; `{zz1}` gives 01, 02, 03…; `{zzz1}` gives 001, 002… The "i" in the field shows this **Syntax**.
3. If you wish, fill **Find and replace**: **Text to find** and **Replace with**, with **Regex** for a regular expression.
4. Under **Preview**, set the order of the files (it decides the numbering): **Reverse**, the sort button (**Custom**, **Name (A-Z)**, **Date (newer)**, **Size (smaller)**, **Type**), or hold a row and drag it.
5. Tap **Preview**: each file shows its new name. If two names collide, the button stays greyed until you change the pattern.
6. Tap **Rename**.

Example: `Holiday {zz1}{e}` renames the selected photos Holiday 01.jpg, Holiday 02.jpg…

### Delete files, and get them back

1. Select the files and tap the bin.
2. In **Delete Confirmation** ("Do you really want to delete the selected files?"), **Move to Recycle Bin** is ticked: the files go to the recycle bin. Untick it to delete them for good. If you change the box, **Remember this choice** appears; tick it to keep that choice for next time.
3. Tap **Confirm** (**Dismiss** cancels).

To get a file back: open **Recycle bin** on the home page. Each deletion is a folder named with a number; open it, select the files, tap the scissors, go to the folder where you want them, tap **Task** and run the task.

To empty the recycle bin: open it, tap **Empty**, then **Confirm**. This deletes for good.

### Compress files into a ZIP

1. Select the files or folders, tap **Options**, then **Compress**.
2. In **Create Archive**, the name proposed is the current folder's name followed by .zip; change it if you wish and tap **Create**. The ZIP is made in the current folder.

**Minimize** closes the window and keeps the task under **Pending tasks**; go to another folder, open **Task** and tap it to get the window again and create the ZIP there.

### Open or unpack an archive

- A .zip (or .jar) file: tap it. You browse it like a folder. You can open its files, create, rename and delete inside it, and copy files out of it or into it with the usual tasks. A file opened from a ZIP and changed in another app is put back into the ZIP when you return to the list.
- Any other archive (7z, rar, tar, tar.gz, tar.bz2, tar.xz, iso, cab, lzh, cpio, deb, rpm and a few more): tap it. The app says "Extracting NAME…", unpacks it into a new folder beside it, named after the archive ("book.tar.gz" gives "book", or "book (2)" if that exists), opens that folder and says "Extracted to “book”".
- A single compressed file ("notes.txt.gz", .bz2, .xz, .zst…): tapping it puts "notes.txt" beside it.

### Search for a file

1. Go to the folder to search in (the storage itself to search everything).
2. Tap **Search**, type part of the name, tap the magnifier.
3. Tap a result to open it, or hold it and choose **Locate** to see it in its folder.

To search by extension or inside text files, open the sliders icon and switch on **By Extension** or **In Content**.

### Show hidden files

Open the three-dot menu in a folder and tap **Show hidden files**. The same setting is in **Preferences**, **File List**. Hidden files are those whose name starts with a dot.

### Change how a folder is displayed or sorted

- Three-dot menu, **Display mode**: list or grid, number of columns, size, thumbnails.
- **Sort**: by name, date, size or type.

In both sheets, **Apply to this folder only** keeps the choice for this folder alone.

### Bookmark a file or a folder

Hold it, tap **Options**, then **Add to bookmarks** (message **Added to bookmarks**). Find it under **Bookmarks** in the bottom bar or on the home page.

### Pin a file or a folder to the home page

Hold it, tap **Options**, then **Pin to home tab** (message **Done**). It appears under **Pinned Files** on the home page. To unpin, hold its row on the home page and tap the bin.

### Put a shortcut on the phone's home screen

Hold one file or one folder, tap **Options**, then **Add to home screen**, and confirm in your launcher. The shortcut opens the app on that folder, or opens that file.

### Share files

Select one or more files (no folder), tap **Options**, then the share icon, and choose the app.

### See the size of a folder or the checksum of a file

Select it and tap the "i" icon. For a folder, **Size** and **Contents** are computed; for a file, **MD5** and **SHA-256**. Hold a value to copy it.

### Go straight to a path

Switch on **Jump to path** in **Customize home tab**, tap it on the home page, type the path in **Destination path** and tap **Open**. The button reads **Invalid path** as long as the path does not exist. The folder opens in a new tab.

### Copy the path of a folder

Hold its name in the path bar. For a file, use **Location** in its properties, or **Copy path** in a search result.

### Choose the tabs opened at start

Open the folder you want, tap its tab, choose **Add to startup tabs** (message **Added as startup tab**). Reorder or remove them in **Manage startup tabs**. Or switch on **Remember last session** in the preferences to reopen the tabs you had when leaving.

### Install an APK, or look inside it

Tap the .apk file, then **Install** (or **Update**). **Explore** shows its contents.

### Save the APK of an installed app

1. Open **Apps** from the home page, tap the app, tap **Extract** (message **New task has been added**).
2. Go to the folder where you want the file, tap **Task** and run the task.

### Turn an .apks, .xapk or .apkm file into an APK

Hold the file, tap **Options**, then **Convert to APK**. The result is created beside it: "name-signed.apk", or "name-unsigned.apk" when **Auto sign merged APK bundle files** is off.

### Edit a text file

1. Tap the file (or **Options**, **Edit with text editor** for a file of another kind). Files over 15 MB are refused.
2. Edit, then tap the diskette. The app says **Saved**.

If you leave the app while files are unsaved, it asks "Some files in the text editor are not saved. Do you want to save them now?" with **Save** and **Ignore**.

### Move or copy the app's settings to another phone

1. **Preferences**, **Other**, **Export preferences**. The app says **Exported to /.prism/preferences.prismPrefs**.
2. Copy that file to the other phone (the .prism folder is hidden: show hidden files to see it).
3. There, tap the file in Reader's Files. In **Import Preferences** ("Do you want to override your current preferences with the ones contained in the selected file?") tap **Confirm**. The app says **Preferences imported successfully**.

## Settings

Three-dot menu, **Preferences**.

### Appearance

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **Theme** | Black on white or white on black | **Light**, **Dark**, **Follow system** | **Follow system** |
| **Show bottom options bar labels** | The words under the icons of the bottom bar | on, off | on |
| **Date time format** | How dates are written in lists and properties | yyyy-MM-dd HH:mm:ss; yyyy-MM-dd; dd-MM-yyyy HH:mm:ss; dd-MM-yyyy; MMM dd, yyyy HH:mm:ss; MMM dd, yyyy; MMMM dd, yyyy; EEE, MMM dd, yyyy | MMM dd, yyyy HH:mm:ss |
| "Hide main toolbar" | Removes the top bar; the line of counts moves under the path bar, **+** and the three-dot menu move to the right of the tabs, and **About** joins that menu | on, off | off |

### File List

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **File list size** | Size of icons and text in lists | **Extra small**, **Small**, **Medium**, **Large**, **Extra large** | **Medium** |
| **Show hidden files** | Shows files whose name starts with a dot | on, off | off |
| **Show folder's content count** | Adds "folders: 2, files: 9" to each folder's line | on, off | off |

### File Operation

| Setting | What it changes | Default |
|---|---|---|
| **Auto sign merged APK bundle files** | "Automatically sign merged APK bundle files with a test key": the APK made by **Convert to APK** is signed so that it can be installed | on |

### Behavior

| Setting | What it changes | Default |
|---|---|---|
| **Long click to show file's options menu** | Holding a file selects it and opens the options sheet at once | off |
| **Disable pull down to refresh** | Pulling a list down no longer refreshes it | off |
| **Skip home screen when closing tabs** | Back at the top folder no longer replaces the tab with the home page | off |
| **Back navigation to close tabs** | Back on a tab other than the first closes it | on |
| **Remember last session** | Reopens the tabs you had when leaving ("if enabled, startup tabs will be ignored") | off |
| **Confirm before exiting the app** | Back must be pressed twice to leave (**Press again to exit**) | on |
| **Use built-in viewers** | "Automatically open supported files with built-in viewers"; off, text, pictures, audio, video and PDF go to other apps | on |

### Recent Files

| Setting | What it changes | Default |
|---|---|---|
| **Extensive recent files scan** | "Scan hidden files and folders": recent files inside hidden folders are listed too | on |
| **Excluded paths** | "Manage excluded paths": folders left out of the recent files. Type a path in **New Path** (the example shown is /storage/emulated/0/example) and tap **+**; the bin removes one. Empty, the sheet says **No excluded paths** and **Add new path to be excluded from the recent file scanner** | none |

### Text Editor

| Setting | What it changes | Default |
|---|---|---|
| **Recent files limit** | "Choose the maximum number of recent files to show": 5, 10, 15, 25 or "Unlimited" | "Unlimited" |
| **Pin Numbers line** | Line numbers stay in place when scrolling sideways | on |
| **Auto symbol pair** | Typing an opening bracket or quote adds the closing one | off |
| **Auto indentation** | A new line starts at the indentation of the previous one | on |
| **Magnifier** | A magnifier appears while moving the cursor | on |
| **Use ICU selection** | Another way of finding where a word starts and ends when you select it | off |
| **Delete empty lines** | Backspace removes an empty line in one go | off |
| **Delete tabs** | Backspace removes a run of spaces in one go | on |

**Word wrap** and **Read only**, both off by default, are set from the editor's menu.

### Other

- **Export preferences** ("To import, locate and open the exported file").
- **About**.

Settings kept outside this screen: the default sorting (sheet **Sort by**), the default display (sheet **View Configuration**), the home layout, the startup tabs, and whether deleting goes through the recycle bin (**Remember this choice** in the delete window).

## Your data

Everything stays on the phone. The app has no network permission and sends nothing to anyone. The two rows **Github** and "Prism File Explorer" of the About card only ask your browser to open a web page.

What the app keeps:

- In its private storage: all settings, bookmarks, pinned files, startup tabs, the sorting and display chosen per folder, the default apps per kind of file, and the logs.
- In a hidden folder named ".prism" at the top of the internal storage: the recycle bin (folder "bin", one numbered folder per deletion), the exported settings ("preferences.prismPrefs") and the text editor's folder ("textEditor", with "symbols.txt", the list of symbols of the editor's bottom bar).
- Temporary copies of files opened from inside a ZIP, removed when the app starts and when it closes.

The recycle bin is never emptied by itself: files moved there keep using space until you empty it.

Export and import: **Export preferences** writes one file with all the settings listed above; opening such a file in the app replaces all current settings with its contents. There is no sync.

Uninstalling removes the private storage (settings, bookmarks, logs). The ".prism" folder is an ordinary folder of your storage: the recycle bin and the exported settings stay there until you delete them. The app lets Android's own backup save its settings.

## With the other apps

- Reader's Files is offered by Android as a viewer when another app opens a PDF, a text file, a picture, an audio file or a video.
- The text viewer opened that way is the same editor; when you leave with unsaved changes it asks "Do you want to save the file?" with **Save** and **Ignore changes**.
- Files are shared to other apps with the share icon of the options sheet, opened in other apps with **Open with**, and pictures are handed to an editor with the pencil of the image viewer.
- **Add to home screen** puts a shortcut to a file or a folder on any launcher that accepts shortcuts.
- Updates come from the F-Droid repository of the Reader's apps or from Reader's Installer.

The app offers no home-screen widget.

## Limits

- No network: no cloud, FTP, SMB or other remote storage.
- Android closes the "Android/data" folders to every file manager since Android 11. Most folders under **Root** are not readable either: the app does not use root access.
- Archives: only ZIP files can be created, and only ZIP files (with .jar, .apk, .apks) are browsed in place; the other formats are unpacked whole, without a progress window. Password-protected 7z, rar and similar archives are refused. Links stored inside an archive are not recreated.
- Copying or moving to the folder the files already are in is refused; there is no "duplicate".
- The recycle bin has no "restore" button: you move the files back yourself.
- The text editor refuses files over 15 MB. Searching inside files skips files over 50 MB and looks only at text and code files.
- The audio player's **Equalizer** sliders move but do not change the sound.
- The audio and video players play one file at a time; there is no playlist.
- The **Documents** category lists PDF, Word, Excel and PowerPoint files only; **Archives** lists zip, rar, tar, gzip and 7z files only.
- In the category lists, the app relies on Android's media index: a file just copied may take a moment to appear.
- A few labels are in English whatever the language: "Hide main toolbar", "Sort Method", "Display Options", "Image Details", the log filters, "Unlimited", "and 2 more", "3 of 20", the kinds in the **Open with** sheet.

## Messages and problems

### Starting and browsing

- **Storage access permission is required**: you came back without granting the access. Tap **Grant Access** again and switch on the access for Reader's Files.
- **This folder is inaccessible**: Android does not let the app read this folder (system folders, "Android/data").
- **Empty** with **Show hidden files in settings to see all files**: the folder has no visible file; it may contain hidden ones.
- **Press again to exit**: press Back a second time within two seconds to leave.
- **Invalid path**: the path typed in **Jump to path** does not exist.

### Opening files

- **Could not find any app that can open this type of files**: no installed app accepts this file. Try **Open with** and the kind "Any".
- "No app found to open this file.": the app chosen as default for this kind of file is no longer installed. Use **Remove default opening method**.
- **Failed to open this file**: the other app refused the file.
- **Invalid zip file**: the ZIP is damaged or is not a ZIP.
- **Failed to extrcat file** (spelled this way in the app): a file inside a ZIP could not be taken out to be opened.
- "Extracting NAME…", "Extracted to “NAME”": an archive is being unpacked, then is unpacked.
- **This archive is protected by a password and cannot be extracted**: the app does not ask for passwords.
- **The archive is empty**: nothing to unpack.
- "The archive could not be extracted: REASON": the archive is damaged or of a format the app does not read.
- **Invalid APK**: the file is not a valid app package.
- **Invalid PDF**, **Failed to load PDF** (under **Error**): the PDF cannot be read.
- **Loading PDF…**, **Loading image…**: wait.
- **Failed to load image**, **Check if the file exists and try again**: the picture is missing or damaged.
- **No app found to edit this image**: no installed app edits pictures.

### Creating, renaming, deleting

- **Invalid file name**, **Invalid folder name**: the name is empty or contains one of `: / * ? " < > |`.
- **File with similar name already exists**: choose another name.
- **Failed to create file**, **Failed to create folder**: the folder cannot be written to.
- **Error creating recycle bin folder**: the recycle bin could not be prepared; nothing was deleted.

### Tasks

- **New task has been added**: the copy or move is waiting; go to the destination and run it from **Task**.
- **Tasks cannot be run here**: you are in a category or a search list; go to a real folder.
- **Task completed**, **Task failed**, **Task has been paused**: the outcome. A failed or paused task waits in the **Tasks** sheet; hold it to read why, tap it to continue.
- **Invalid destination directory.**: the destination is the folder the files are already in.
- **Some files are moved into their subdirectories, those will be excluded.**: you tried to move a folder into itself.
- **No source files were found.**, **The destination was missing.**: the files or the destination disappeared meanwhile.
- "Something went wrong:" followed by a reason: the operation failed at that point (no space left, no right to write…).
- **Task is not ready.**, **Task not found.**, **Task is not in pending state**, "Task cannot be continued from current state: …", **This task is currently running**: the task cannot be started or removed in its present state; wait for it to end or remove it from the list.
- **Task aborted**: you stopped it.
- **Unsupported source/destination combination**, **unsupported source file**: this operation is not possible between these places.
- **Failed to copy files to zip**, **Failed to extract files from zip**, **Failed to copy zip entries**, **Failed to replace original zip file**, **Failed to delete original zip file**: an operation inside a ZIP failed; the ZIP may be read-only or damaged.
- **Failed to delete file**, **Failed to rename file**: the file is protected or no longer there.
- **Invalid APK bundle file**, **Failed to convert APK bundle to APK**, **Failed to sign the merged APK file**: **Convert to APK** could not use this file. **APK bundle file successfully converted to APK** is the success message.

### Search

- **Something went wrong, check logs**: the search stopped on an error; open **Logs** from the About card.

### Text editor

- **Saved**, **Failed to save**: result of saving.
- **Permission denied**: a file opened from another app cannot be written back.
- **File too large, consider using a dedicated text editor instead.**: over 15 MB.
- **File not found**, **File no longer exists**: the file was deleted or moved meanwhile.
- **Warning**, "The source file has been changed, do you want to reload it?": another app changed the file. **Reload** takes the new contents, **Cancel** keeps yours.
- **Warning**, "This file has not been saved, do you want to save it?": you are closing an unsaved file from **Recent Files**. **Save** or **Ignore changes**.
- **Invalid position**: what you typed in **Jump to position** is not a line number or "line:column".
- **Failed to load symbols file**: the file "symbols.txt" of the editor is damaged; the standard symbols are used.

### Settings

- **Exported to /.prism/preferences.prismPrefs**: the export succeeded.
- **Preferences imported successfully**, **Invalid preferences file**: result of an import.
- **Added to bookmarks**, **Done**, **Added as startup tab**, **Removed from startup tabs**, **Copied to clipboard**, **Path copied to clipboard**: confirmations.


# Reader's Night Filter

*Android 1.0.0*

## What it is

Reader's Night Filter is one switch that turns the phone's screen gray, as warm as the phone allows, and dim, for reading in the evening. It does not lay a coloured veil over the screen: it drives three of Android's own display settings together (colour correction set to grayscale, Night Light at its warmest, extra dim) and puts them back as they were when you switch off. The same switch is available in the app, in the quick settings, in a home-screen widget and as a tile in Reader's Launcher.

The app needs a permission that Android only gives from a computer, once. It does not need root. It cannot remove all the blue from the screen, it has no timetable (you switch it on and off yourself), and it never uses the network.

The app runs on Android 9 and later, in six languages: English, French, German, Spanish, Portuguese and Russian.

## First start

### The permission, given once from a computer

Android lets an app change the screen's colours only after a special permission. It cannot be granted on the phone itself: it is given once, from a computer. Until then the app shows, instead of the switch, a page titled **one step left** with this text:

"Android lets an app change the screen’s colours only after a permission that is given once, from a computer. Turn on USB debugging in the phone’s developer options, connect the phone to the computer by USB, and run this command on the computer:"

Under the text the app displays the command:

```
adb shell pm grant com.freedomfighter.readersnight android.permission.WRITE_SECURE_SETTINGS
```

The steps, as the app gives them:

1. On the phone, turn on USB debugging in the developer options.
2. Connect the phone to the computer by USB.
3. On the computer, run the command above. It uses `adb`, Android's tool for computers, which must be present on the computer; the app does not install it.
4. Look at the phone: the page **one step left** gives way to the switch by itself within a couple of seconds. The app says so at the bottom of the page: "This page gives way to the switch as soon as the permission is there."

To avoid retyping the command, tap **copy the command**: the command is placed in the phone's clipboard and the line reads **copied** for a moment. You can also select the command's text on the page with a long press.

The permission stays after the phone restarts and after the app is updated. It is lost when the app is uninstalled: after a new installation, run the command again.

### No account, nothing else to allow

The app asks for no other permission, no account and no server. Once the permission is given, the main screen shows **filter off** and "the screen shows its usual colours". All three parts of the filter are already chosen: grayscale on, warm tint on, dimming medium.

## The screens

### The main screen: night filter

The title at the top reads **night filter**. On the right of the title, **⋯** opens the menu.

Under the title, a large block shows the state:

- **filter off**, with "the screen shows its usual colours";
- **filter on**, on an inverted background, with the parts in use, for example "grayscale · warm tint · dimmed". If you switched all three parts off, it reads "nothing chosen: the screen stays as it is".

Tapping this block switches the filter on or off.

Under **what the filter does**, three rows choose the parts. Each row shows its name on the left and its current value on the right; tap the row to change it.

- **grayscale**: **on** or **off**. Removes the colours from the screen.
- **warm tint**: **on** or **off**. Sets Android's Night Light to the warmest the phone accepts.
- **dimming**: each tap moves to the next value, **off**, **light**, **medium**, **strong**, then back to **off**. Darkens the screen beyond the lowest brightness, with Android's extra dim. This row only appears on Android 12 and later.

A change made while the filter is on is applied to the screen at once.

Below the rows, a note recalls the limit: "The warm tint is the warmest the phone allows. It removes much of the blue, not all of it: Android does not let an app go further."

At the very bottom, a row reads **turn the filter on** or **turn the filter off**, depending on the state. It does the same as tapping the state block.

### The menu (⋯)

- **turn the filter on** / **turn the filter off**: the same switch. This entry is absent as long as the permission has not been given.
- **black on white** or **white on black**: switches the app's colours to the ones named.
- **settings**: opens the settings screen.

Tap outside the menu, or press back, to close it.

### The page "one step left"

Shown in place of the state block and the rows until the permission has been given. It contains the explanation, the command, the row **copy the command** and the sentence about the page giving way to the switch. See "First start". The menu **⋯** remains available.

### Settings

Title **settings**, with **←**: tap the title to go back. The screen holds:

- **add to quick settings**, with "the switches under a swipe down from the top of the screen" beneath it (Android 13 and later). On Android 9 to 12 this row is replaced by a text explaining how to do it by hand.
- the four rows about the app's look: **colours**, **text size**, **font**, **haptic tick** (see "Settings" below). Each row shows the current value in large letters and the setting's name beneath it.
- **Reader's Night Filter**, "a gray, warm and dim screen for the evening", and the credits line. These two rows do nothing when tapped.

### The quick-settings tile

Named **Night filter**. It is lit while the filter is on. A tap switches the filter on or off without opening the app. A long press opens the app. If the permission has not been given, a tap closes the quick settings and opens the app on the page **one step left**.

### The widget

On the left, **filter on** or **filter off** and, beneath, the parts chosen (for example "grayscale · warm tint · dimmed"), or **one step left** if the permission is missing. On the right, a switch reading **on** (filled) or **off** (framed).

- Tap the switch: the filter goes on or off.
- Tap the words: the app opens.
- Without the permission, the switch opens the app as well.

## How to

### Give the permission from a computer

1. Open the app. It shows **one step left**.
2. On the phone, turn on USB debugging in the developer options.
3. Connect the phone to the computer by USB.
4. On the computer, run: `adb shell pm grant com.freedomfighter.readersnight android.permission.WRITE_SECURE_SETTINGS`
5. Wait a moment: the page is replaced by the switch.

### Switch the filter on or off

In the app: tap the state block at the top, or the row **turn the filter on** / **turn the filter off** at the bottom, or the same entry in the menu **⋯**.

Outside the app: tap the **Night filter** tile in the quick settings, the switch of the widget, or the switch of the tile in Reader's Launcher.

### Choose what the filter does

1. Open the app.
2. Under **what the filter does**, tap **grayscale** or **warm tint** to set it **on** or **off**.
3. Tap **dimming** until it shows the strength you want: **light**, **medium**, **strong**, or **off**.

The choices are kept. They apply at once if the filter is on, otherwise the next time you switch it on.

### Keep the colours but warm and dim the screen

Set **grayscale** to **off** and leave **warm tint** on, with the **dimming** you want.

### Add the switch to the quick settings

On Android 13 and later:

1. Open the menu **⋯**, then **settings**.
2. Tap **add to quick settings**.
3. Confirm in the box Android displays.

On Android 9 to 12, the app gives the manual way: "To add the switch to the quick settings: swipe down twice from the top of the screen, tap the pencil, and drag “Night filter” among the switches."

### Put the widget on the home screen

1. In your launcher's list of widgets, find **Reader's Night Filter** (described as "the night filter, on or off").
2. Place it on the home screen. It takes about four cells by two, and can be resized in width and height.

### Open the app from the quick settings

Press the **Night filter** tile for a long time.

### Change the app's colours

Open the menu **⋯** and tap **black on white** (or **white on black**). The same change is in **settings**, row **colours**.

## Settings

The parts of the filter are chosen on the main screen:

| Setting | Choices | Default |
|---|---|---|
| **grayscale** | **on**, **off** | **on** |
| **warm tint** | **on**, **off** | **on** |
| **dimming** (Android 12 and later) | **off**, **light**, **medium**, **strong** | **medium** |

The app's look is chosen in **settings**. Tap a row to move to the next choice.

| Setting | Choices | Default | What it changes |
|---|---|---|---|
| **colours** | **white on black**, **black on white** | **white on black** | The colours of the app and of its widget. |
| **text size** | **small**, **medium**, **large** | **medium** | The size of all text in the app. |
| **font** | **sans-serif**, **serif**, **mono** | **sans-serif** | The typeface of the app. |
| **haptic tick** | **on**, **off** | **on** | A short vibration when you switch the filter or change one of its parts in the app. |

The widget takes the app's colours when you leave the app.

## Your data

Everything stays on the phone. The app has no network permission: it cannot send or receive anything, there is no account and nothing is collected.

The app keeps only: your choices (the three parts, the look), whether the filter is on, and the values Android's display settings had just before the filter was switched on, so that it can put them back.

What switching off restores:

- colour correction: its previous state and its previous mode;
- Night Light: on or off as before, your own strength, your own schedule. While the filter is on with **warm tint**, the Night Light schedule is suspended, so that sunrise does not end the tint;
- extra dim: Android does not let an app read this setting, so the app cannot know what it was. Switching the filter off turns extra dim off, and leaves its strength where the filter set it.

There is no export, no import and no synchronisation. The app's data is not included in Android's backups.

Uninstalling removes the choices and the permission. Switch the filter off before uninstalling: your display settings are put back only at the moment the filter is switched off.

The state of the filter and its switch are open to one other app only, Reader's Launcher, which the app recognises by its signature.

## With the other apps

### Quick settings

The tile **Night filter** (see "The screens").

### Home-screen widget

One widget, **Reader's Night Filter**, for any launcher that accepts widgets: the state in words and a switch.

### Reader's Launcher

Reader's Launcher has its own tile for the filter. In the launcher's menu, choose **add widget**, then **night filter** ("the screen gray, warm and dim: Reader's Night Filter on and off").

The tile shows **filter on** or **filter off**, with **night filter** beneath, and a switch on the right: **●** when on, **○** when off.

- Tap the switch: the filter goes on or off.
- Tap the words: Reader's Night Filter opens.
- If the permission has not been given, the tile reads **one step left in the app**, and the switch opens the app.
- If Reader's Night Filter is not installed, the tile shows its name in gray, without a switch; a tap opens the app's page on the web.

## Limits

- The warm tint stops at the warmest Night Light the phone accepts. It removes much of the blue, not all of it; on a Pixel 10, about a fifth of the blue light and half of the green remain. A red-only screen would need root, which the app does not use.
- The permission can only be given from a computer.
- Dimming needs Android 12 or later. On Android 9 to 11 the filter has two parts, grayscale and warm tint.
- The button **add to quick settings** needs Android 13 or later; before that, the tile is added by hand.
- No schedule: the filter does not switch itself on in the evening or off in the morning.
- The warm tint has one strength, the warmest. The three dimming strengths are the only ones.
- If you had Android's extra dim on before using the filter, it is off afterwards: switch it back on in the system settings.

## Messages and problems

**one step left** (in the app, or under the state in the widget) / **one step left in the app** (tile of Reader's Launcher): the permission has not been given, or was lost after a reinstallation. Run the command from a computer, see "First start".

**The tile or the widget opens the app instead of switching.** Same cause: the permission is missing.

**copied**: the command is in the phone's clipboard.

**nothing chosen: the screen stays as it is**: the filter is on but grayscale, warm tint and dimming are all **off**. Switch at least one of them on.

**the screen shows its usual colours**: the filter is off.

**The page "one step left" stays after the command.** The page checks every second or two while it is open. If it does not change, the command did not reach the phone: check that USB debugging is on, that the phone is connected by USB, and run the command again.

**The filter shows "filter off" although I did not switch it off.** If you turn grayscale off in the system settings while the filter is on, the app follows: the next time you open the app or the quick settings, it considers the filter off and puts the other settings back. When **grayscale** is not among the chosen parts, the same applies to Night Light switched off in the system settings.

**There is no "dimming" row.** The phone runs Android 9, 10 or 11.

**There is no "add to quick settings" row.** The phone runs Android 12 or earlier; follow the text shown in its place.

**The screen still looks a little blue.** That is the limit Android sets, recalled by the note on the main screen.




<!-- Also in the installer -->


# ePub Magazine Reader

*Android 0.2.26-magazine*

## What it is

ePub Magazine Reader reads newspapers and magazines delivered as EPUB files, on a phone or an e-ink tablet. An issue opens as a contents page with one card per article (section, title, author, picture), then each article is shown on its own, cut into full pages that you turn with a tap: nothing scrolls. New issues can be fetched by themselves from a shared kDrive folder or from a WebDAV folder, picked from a folder on the device, or opened from another app.

It is built on the book reader Book's Story, of which it keeps the library, the file browser and the themes. It is deliberately not a general book reader: it opens EPUB files only, and it has no bookmarks, no highlighting, no search inside the text, no dictionary and no choice of fonts.

On the phone the app is named **ePub Magazine reader**.

## First start

The app asks for no Android permission. It only reads the folders you choose yourself, and uses the network for the sync you set up.

At the first start a welcome screen appears: **Welcome to ePub Magazine reader!**

1. Under **Scan preferences**, tap **Add folder** and choose, in the Android folder picker, the folder where your EPUB files are. You can add several folders. Each one is listed with a cross to remove it. This step is optional.
2. Tap **Next**.
3. The screen shows **Everything is done!** and **Setup completed.** Tap **Done**.

The app then adds every EPUB found in the chosen folders (subfolders included) to the library and shows the **Library**. If files were found, the message **All selected books were successfully added.** appears.

Pressing the Back button on the welcome screen closes the app.

When the library is empty it shows **Read your favorite books and sort them between categories** and a button **Add a book**, which leads to the **Browse** screen. When **Browse** has nothing to show, it displays **Expand the library's book collection with your downloads** and a button **Set up scanning**, which leads to the folder settings.

There is no account to create. A sync folder is entered later, in **Settings** then **Sync** (see "Fetch the issues from a shared kDrive folder" and "Fetch the issues from a WebDAV folder").

## The screens

The app has two main screens, **Library** and **Browse**, reached with the bar at the bottom (on a wide screen, a column on the left side). The three-dot button at the top right of both opens a panel with **About app** and **Settings**.

While the app is on screen, the display never goes to sleep by itself.

### Library

The list of your issues. At the top: the title **Library** followed by the number of issues, then three buttons.

- The magnifying glass opens a search field (**Search…**). Type part of a title: the list is filtered about half a second after you stop typing. The arrow on the left closes the search.
- The sort button opens a panel with two orders, **Last modified** and **Alphabetically**. Tap an order to choose it; tap the chosen order again to reverse it (the arrow shows the direction).
- The three dots open **About app** and **Settings**.

Each line shows the cover, the title and a small percentage badge. The badge stays at 0 %: the app remembers the article where you stopped, not a percentage.

- Tap an issue to open it.
- Long press an issue to select it. The top bar then shows a cross (cancel the selection), **1 selected** (the count), a "select all" button and a bin. Tap other issues to add them to the selection or take them out.
- Pull the list down to refresh it. If a share link or a WebDAV URL is set in **Sync**, this also fetches the new issues at once.

The Back button cancels a selection, then closes the search, then leaves the app.

### Browse

The files found in your scan folders that are not yet in the library, grouped by folder. Each group has a heading with the folder's path and a pin: tap the pin to keep that folder at the top of the list.

Each file shows its name, its size and its date. The screen lists files ending in .epub, .pdf, .fb2, .txt, .html, .htm and .md, but only EPUB files can be added to the library.

- Tap a file to select it, tap again to deselect it.
- Long press a file to select every file of its folder.
- With a selection, the top bar shows a cross, the count, a "select all" button and a check mark. The check mark opens the **Add books?** dialog (see "Add issues from a folder of the device").

At the top, the magnifying glass searches by file name. The filter button opens a panel with three tabs:

- **Sort**: **Alphabetically**, **File format**, **Last modified**, **File size**. Tap the chosen order again to reverse it.
- **Filter**: one box per file type (.epub, .pdf, .fb2, .txt, .html, .htm, .md). With no box ticked, every type is shown. The filter button is coloured when a filter is on.
- **Display**: **Display mode** (**List** or **Grid**) and, in grid mode, **Grid size**.

Pull the list down to scan the folders again. The Back button returns to the **Library**.

### Contents of an issue

Opening an issue shows its contents, cut into pages that fit the screen.

- The bar at the top has three zones. The left arrow goes to the previous page of the contents, the right arrow to the next one. The middle zone shows the title of the issue (or its publisher and date when it has no title); tapping it returns to the **Library**.
- Each card shows the section, the title of the article, the author when the issue gives one, and the article's picture on the right when it has one. Tap a card to read the article.
- At the bottom, a counter such as **2 / 5** gives the page of the contents when there is more than one.
- The bar at the very bottom has a house in the middle: it returns to the **Library**. The minus and plus on either side are greyed on this screen.

The contents are not swiped: use the two arrows. The Back button returns to the **Library**.

When an issue is opened again after another one, or after the app was restarted, the contents open on the page that holds the article you last read, and that card is framed.

An EPUB that holds a single article opens straight on that article, without contents.

An EPUB that is not laid out as a magazine opens the same way: each chapter becomes a card, labelled with the publisher or the title of the book.

### Article

The article fills the screen, black on white whatever the theme, in full pages.

- Tap the right third of the screen to go to the next page. On the last page, the same tap opens the next article.
- Tap the left third to go back one page.
- Tap the middle third to show or hide the two bars.

The top bar: the left arrow opens the previous article, the right arrow the next one, and the middle zone, which shows the section, returns to the contents.

The bottom bar: the minus makes the text smaller, the plus makes it bigger, and the house in the middle, next to the current size in percent, returns to the **Library**.

The bars hide again each time the article changes. The Back button returns to the contents.

### Settings

Reached with the three dots, then **Settings**. Five entries: **General**, **Appearance**, **Library**, **Browse**, **Sync**. Each is described under "Settings" below.

The button at the top right of this screen shows the welcome screen of the first start again.

### About app

Reached with the three dots, then **About app**.

- **App version**: the name and the version of the app.
- **Based on Book's Story by Acclorite**, with the line **Pierre Gallaz · developed with Claude Code**.
- **Open source licenses**: the list of the software libraries used; tap one to read its licence.
- **Credits**: the projects the original reader thanks; tap one to open its web site.
- **Report a bug**, **Contributors**, **Help translate**, **Support development**, a tap on **App version**, and the small icons at the bottom open pages of Book's Story, the original project, in your browser, not pages of this app.

### The crash screen

If the app stops on an error, a screen titled **Oops! The app crashed.** shows the technical report. **Copy** puts it in the clipboard, **Report** opens the Android share sheet to send it with the app of your choice.

## How to

### Add issues from a folder of the device

1. Open **Settings**, **Browse**, and under **Scan** tap **Add folder**. Choose the folder in the Android picker.
2. Go to **Browse**. The EPUB files of the folder and of its subfolders are listed.
3. Tap the files you want, or long press one to take the whole folder.
4. Tap the check mark at the top right. The **Add books?** dialog lists the files with their title and author; tap a line to leave it out. A file that could not be read is shown in red.
5. Tap **OK**. The app returns to the **Library** and shows **All selected books were successfully added.**

The files stay where they are: the app reads them in your folder.

### Open an EPUB received in another app

In a file manager, a messaging app or a browser, tap the EPUB file and choose **ePub Magazine reader** in the Android "Open with" list. The app keeps its own copy of the file and opens the contents of the issue.

### Fetch the issues from a shared kDrive folder

1. In kDrive, create a public share link for the folder that receives your issues (a link without password).
2. In the app, open **Settings**, **Sync**.
3. Tap **kDrive share link**, paste the link and tap **OK**.
4. Tap **Sync now** to fetch the issues at once.
5. Turn on **Enable sync** to have it done by itself, and set **Sync interval**.

### Fetch the issues from a WebDAV folder

This works with any WebDAV server (Nextcloud, kDrive and others).

1. Open **Settings**, **Sync**. Leave **kDrive share link** empty: when a share link is present, it is used instead of WebDAV.
2. Under **WebDAV (alternative)**, tap **WebDAV URL** and enter the full address of the folder that holds the EPUB files.
3. Tap **Username**, then **Password**, and enter those of your server. All three fields are needed.
4. Tap **Sync now**, then turn on **Enable sync** if you want it automatic.

### Fetch the new issues right now

Either pull the **Library** down, or open **Settings**, **Sync** and tap **Sync now**. In **Sync**, the line shows **Syncing…**, then the result, for example **2 new, 14 skipped**: the number of issues downloaded and the number already on the device.

### Read an issue

1. In the **Library**, tap the issue.
2. In the contents, turn the pages with the two arrows at the top and tap the card of an article.
3. Turn the pages by tapping the right of the screen. At the end of the article, one more tap on the right opens the next article.
4. To go back to the contents, press Back, or tap the middle of the screen and then the middle of the top bar.

### Go on where you stopped

Tap the issue in the **Library**. If you had read an article of it, the app opens that article directly, at its first page. The contents are right behind: press Back to reach them.

### Jump to the previous or the next article

Tap the middle of the screen to show the bars, then the left or right arrow of the top bar.

### Make the text bigger or smaller

In an article, tap the middle of the screen, then the plus or the minus in the bottom bar. The size goes from 70 % to 220 % in steps of 10. It starts between 100 % on a narrow phone and 140 % on a tablet. The size is kept while you move from article to article; it returns to the starting value when you go back to the contents.

### Find an issue

In the **Library**, tap the magnifying glass and type part of the title.

### Sort the library

In the **Library**, tap the sort button and choose **Last modified** (the date of the file) or **Alphabetically**. Tap the same line again to reverse the order.

### Remove issues from the library

1. In the **Library**, long press an issue, then tap the others to remove.
2. Tap the bin.
3. The **Delete books?** dialog reminds you that the issues leave the library but that the files are not deleted. Tap **OK**.

The message **All selected books were successfully deleted.** confirms it. An issue that came by sync and is still in the folder on the server is downloaded again at the next sync.

### Show the library as a grid of covers

Open **Settings**, **Library**, and under **Display mode** choose **Grid**. **Grid size** and **Title position** then appear.

### Change the language

Open **Settings**, **General**, and tap a language under **App language**.

### Switch to a dark theme

Open **Settings**, **Appearance**, and under **Dark theme** choose **Enabled**, or **System** to follow the phone. The article page stays black on white.

### Stop giving access to a folder

Open **Settings**, **Browse**, and tap the cross next to the folder. Neither the files nor the issues already in the library are deleted, but an issue whose file sits in that folder can no longer be opened.

### See the welcome screen again

Open **Settings** and tap the button at the top right. At the end, **Done** adds to the library every EPUB of the scan folders that is not in it yet.

## Settings

### General

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **App language** | Language of the app | 20 languages | The language of the phone if it is in the list, otherwise English |
| **Double back press to exit** (**Press back twice to exit the app**) | In the **Library**, a first press on Back shows **Press back again to exit**; a second one within a second and a half closes the app | on, off | off |

### Appearance

Under the heading **Theme preferences**.

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **Dark theme** | Light or dark screens | **System**, **Disabled**, **Enabled** | **Disabled** |
| **App theme** | Colour palette of the app | **Mercury**, **Neptune**, **Earth**, **Io**, **Enceladus**, **Pluto**, **Mars**, **Callisto**, **Jupiter**, **Ceres**, **Eris**, **Saturn**, **Ganymede**, **Venus**, **Makemake**, **Uranus**, **Iapetus** | **Mercury** (the colours of your Android wallpaper; offered from Android 12), otherwise **Neptune** |
| **Theme contrast** | Strength of the contrast. Shown only for **Neptune**, **Earth**, **Pluto**, **Mars**, **Jupiter**, **Eris**, **Saturn**, **Venus** and **Uranus** | **Standard**, **Medium**, **High** | **Standard** |
| **Pure dark** | Black background in dark theme. Shown only when the dark theme is on | **Disabled**, **Enabled**, **Saver** (only while the phone's battery saver is on) | **Disabled** |
| **Absolute dark** (**Change background color to be completely black**) | Shown only when the pure dark background is active | on, off | off |
| **Show navigation labels** (**Show navigation bar labels under icons**) | Shows the words **Library** and **Browse** under the icons of the bottom bar | on, off | on |

### Library

Under the heading **Display**.

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **Display mode** | List of lines or grid of covers | **Grid**, **List** | **List** |
| **Grid size** | Number of covers per row. Shown in grid mode | **Auto**, or 1 to 10 **per row** | **Auto** |
| **Title position** | Where the title goes in grid mode | **Hidden**, **Below**, **Inside** | **Below** |
| **Show progress** | Shows the percentage badge on each issue | on, off | on |

The sort order is chosen in the **Library** itself: **Last modified** or **Alphabetically**; by default **Last modified**, the most recent file first.

### Browse

**Scan**: the list of the folders the app may read, each with a cross to remove it, and **Add folder**. The note reads: **These folders are used to scan and retrieve files in the Browse. Removing a folder here will not delete actual files or books from the Library. To revoke access, click the corresponding button.**

**Display**:

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **Display mode** | List or grid of files | **List**, **Grid** | **List** |
| **Grid size** | Number of files per row. Shown in grid mode | **Auto**, or 1 to 10 **per row** | **Auto** |

The sort order and the file-type filter are chosen in **Browse** itself, with the filter button; by default **Last modified**, the most recent first, and no filter.

### Sync

| Setting | What it does | Choices | Default |
|---|---|---|---|
| **Enable sync** (**Automatically sync EPUBs from kDrive**) | Fetches the new issues by itself: in the background at the chosen interval, and each time the app is opened if the last sync is more than two minutes old | on, off | off |
| **kDrive share link** (**Paste a public kDrive folder link**) | The public share link of a kDrive folder. Once set, the line shows the end of the link | text | empty |
| **Sync interval** | Hours between two background syncs | 1 to 24 h | 6 h |
| **Sync now** | Fetches the new issues at once. Below it: **Never synced**, or **Last sync:** with the date and time, or the result of the sync just done | | |
| **WebDAV URL** (**kDrive folder URL**) | Address of the WebDAV folder | text | empty |
| **Username** | Your name on the WebDAV server | text | empty |
| **Password** | Your password on the WebDAV server. Shown as dots once set | text | empty |

The last three are under the heading **WebDAV (alternative)**. They are used only when **kDrive share link** is empty. Tapping a text setting opens a dialog titled **Edit** with **Cancel** and **OK**.

## Your data

**On the device.** The list of issues, their covers and the article where you stopped in each are kept in the app's private storage. Issues fetched by sync and files opened from another app are copied there too. Issues added from **Browse** are not copied: the app reads them in your folder, and they must stay there.

**Over the network.** The app connects only for the sync:

- with a share link, to the kDrive service, without any account;
- with WebDAV, to the server whose address you entered, with your username and password.

Nothing else is sent, and nothing is ever uploaded. The WebDAV password is kept on the device in encrypted form; the key that reads it is held by Android and never leaves the device. The links of **About app** open in your browser.

**How the sync works.** The app lists the files placed directly in the folder (not in its subfolders) whose name ends in .epub, and downloads those whose file name is not already the name of an issue in the library. It is one way: it deletes nothing on the server and nothing on the device. An issue replaced on the server under the same name is not downloaded again. A file whose name contains `_blacklisted_` is ignored. The background sync needs a network connection and is tried again later after a failure.

**Removing.** Removing an issue from the library deletes neither your file nor the copy the app holds.

**Backup, export, import.** There is none, and the app is excluded from Android's own backup. Uninstalling the app deletes the library, the settings and the copies it holds; the files in your own folders are not touched.

## With the other apps

- The app offers itself in Android's "Open with" list for EPUB files.
- It has no home-screen widget, and it is not a share target.
- **Report**, on the crash screen, uses the Android share sheet.

## Limits

- EPUB only. The other file types listed in **Browse** cannot be added.
- No bookmarks, notes, highlighting, search inside the text, dictionary, choice of font or margins.
- The article page is always black on white.
- The text size is not kept from one reading session to the next.
- The position inside an article is not kept: an article reopens at its first page.
- The percentage badge of the library stays at 0 %.
- The whole EPUB file is loaded in memory when an article is opened.
- Sync: one way, top level of the folder only; the kDrive link must be public, without password.
- Many screens exist in English only, whatever the language chosen: the **Sync** settings, the messages of the reading screens.
- Android 8.0 or later.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **This ePub is not a supported magazine** | The file is not a readable EPUB. Check that it is complete. |
| **Could not read the file.** / **Could not open the file.** | The file handed over by the other app could not be copied or read. Save it on the device first, then open it again. |
| **Loading…** | The issue or the article is being prepared. |
| **Could not access ePub file.** | The file is no longer where it was, or the app no longer has access to its folder. Put it back, or add the folder again in **Settings**, **Browse**. |
| **Could not parse this ePub.** | The app found no article in the file. |
| **Could not read article.** / **Article not found.** | The article is missing from the file or is damaged. |
| **File not found:** followed by a path | The copy of a file opened from another app is gone. Open the file again from that app. |
| **Book #… not found** | The issue is no longer in the library. Return to the **Library**. |
| **Nothing to display.** / **No content.** | The issue or the article is empty. |
| **Sync failed:** followed by a reason (in the **Library**) / **Failed:** followed by a reason (in **Sync**) | The sync did not complete. The reasons are listed below. |
| … **Invalid kDrive share link** | The text pasted is not a kDrive share link. Copy the link again from kDrive. |
| … **Share is not public** | The link is protected. Create a public link without password. |
| … **WebDAV credentials not configured** | **WebDAV URL**, **Username** or **Password** is empty. |
| … **WebDAV PROPFIND failed: 401** | Wrong username or password. Other numbers: 404, wrong folder address; 403, access refused. |
| … **HTTP** followed by a number | The kDrive service refused the request; check the link. |
| A result ending in **failed**, for example **1 new, 3 skipped, 2 failed** | Some files could not be downloaded or read. They are tried again at the next sync. |
| **Never synced** | No sync has succeeded yet. |
| **Something went wrong.** | Shown when you tap a red file in **Add books?**: the file is not an EPUB or cannot be read. |
| **No app to choose folder found.** | Android has no folder picker available for **Add folder**. |
| **No browser app found.** | No browser to open a link of **About app**. |
| **No app to share found.** | No app to send the crash report with **Report**. Use **Copy**. |
| **Copied** | The crash report is in the clipboard. |
| **Press back again to exit** | **Double back press to exit** is on. |
| **Slava Ukraini!** | Shown when you tap the trident icon at the bottom of **About app**. |
| **Closed source** | In **Open source licenses**, marks a library whose code is not public. |


# Le dictionnaire Littré

*Android 1.1.2*

The app exists in French only: every label on screen is in French whatever the language of the phone. In this chapter the labels are quoted as the app writes them, with their meaning in brackets the first time. On the phone, the app appears under the name **Le Littré**.

## What it is

Le dictionnaire Littré puts the whole of Émile Littré's *Dictionnaire de la langue française* (Paris, Hachette, 1873–1874) on your phone: 78 599 entries with their definitions, quotations and etymologies, and the 1878 supplement where an entry has one. You look a word up by typing its first letters, or you search inside the text of the definitions. A word of the day is shown in the app and can be placed on the home screen as a widget.

Everything is inside the app. It asks for no permission, not even Internet access, has no account and no advertising. It is a reading tool for one dictionary: it does not translate, does not pronounce words aloud, and does not let you add notes or edit anything.

## First start

The app asks nothing: no permission, no account, no server.

The first time it opens, it unpacks the dictionary into its own storage on the phone (about 165 MB). A turning circle is shown for a moment, then the search screen appears with the word of the day.

At that point the **Favoris** (favourites) screen is empty and says **Aucun favori pour le moment** (no favourite for now), and its **Historique** (history) tab says **Aucun historique** (no history).

## The screens

A bar at the bottom of the app gives three screens: **Recherche** (search), **Favoris** (favourites) and **À propos** (about). A fourth screen, the article, opens on top of them when you tap a word.

### Recherche

This is the screen the app opens on. Its title is **Littré**.

At the top is the search field, with the hint **Rechercher un mot…** (search for a word…). To the right of the field:

- a cross, shown only when the field contains text: it empties the field;
- the search-mode button. It switches between the two ways of searching. When it shows the letters A–Z, you are in **Recherche par mot** (search by word). When it shows an open book, in colour, you are in **Recherche dans les définitions** (search in the definitions). A long press on the button displays the name of the mode you are in.

Under the field:

- When the field is empty, the screen shows the **Mot du jour** (word of the day): a card with the word, its grammatical nature, the beginning of its definition, and the line **Appuyez pour lire l'article complet** (tap to read the full article). Tapping the card opens the article.
- When you type, the results appear by themselves a fraction of a second after you stop typing; there is no button to press. Each result is a card with the headword, its grammatical nature in italics (for example *s. f.*), and the first two lines of the definition. Tapping a card opens the article.
- When nothing matches, the screen says **Aucun résultat** (no result).

**Recherche par mot** lists the entries whose headword begins with what you typed, in alphabetical order, twenty at most. Capitals and accents do not matter: typing `etre` finds ÊTRE. The joined letters œ and æ can be typed joined or as two letters: `coeur` and `cœur` both find CŒUR.

**Recherche dans les définitions** looks for what you typed in the headword, the text of the article (definitions, quotations, the historical section) and the etymology. It finds whole words only, and when you type several words it looks for them together, in that order, as a phrase. Capitals and accents do not matter, but a word written with œ or æ must be typed with its joined letter: `cœur`, not `coeur`. It returns fifty entries at most, the most relevant first. The 1878 supplement is not searched.

The search mode goes back to **Recherche par mot** each time the app is restarted.

### The article

The article screen shows, from top to bottom:

- the headword, in capitals as in the dictionary (for example MAISON, or ABAISSÉ, ÉE for an adjective with its feminine);
- its grammatical nature in italics and, when the dictionary gives one, Littré's pronunciation between square brackets;
- the body of the article: the senses, numbered when there are several; the quotations in italics, each followed by its author and reference between square brackets; then, where the entry has them, sections with a heading such as **PROVERBE** or **HISTORIQUE** (the old quotations, century by century);
- a framed box **ÉTYMOLOGIE** (etymology), when the entry has one;
- a tinted box **SUPPLÉMENT (1878)**, when the entry has an addition from Littré's supplement.

Underlined words in colour are cross-references: tapping one opens the article it points to, on top of the current one. When several entries have the same spelling, the cross-reference opens the one it designates. The back arrow returns to the previous article, then to the list you came from.

At the top right are two buttons:

- the star: **Ajouter aux favoris** (add to favourites). When the article is a favourite the star is filled and yellow, and tapping it again does **Retirer des favoris** (remove from favourites);
- the copy button: **Copier l'article** (copy the article). It puts the article on the clipboard as plain text and confirms with **Article copié dans le presse-papiers** (article copied to the clipboard).

Opening an article, by any route, adds it to the history.

### Favoris

This screen has two tabs; you tap a tab or swipe sideways to change.

- **Favoris**: the articles you starred, in the order you added them (the oldest first). Tapping one opens it. When there are none, the screen says **Aucun favori pour le moment** and **Appuyez sur l'étoile dans un article pour l'ajouter ici.** (tap the star in an article to add it here).
- **Historique** (history): the last articles you opened, the most recent first, one hundred at most. An article opened again moves back to the top instead of appearing twice. Tapping one opens it. At the bottom, **Effacer l'historique** (clear the history) empties the list at once, without asking for confirmation. When the list is empty, the screen says **Aucun historique** and **Les articles consultés apparaîtront ici.** (the articles you have read will appear here).

### À propos

An information page, with nothing to tap. It shows the name **Littré**, the subtitle **Dictionnaire de la langue française**, a version line, and three cards:

- **Données lexicographiques** (lexicographic data): « Le Littré » by François Gannaz, littre.org, **Licence Creative Commons BY-SA 3.0**;
- **Texte original** (original text): Émile Littré, *Dictionnaire de la langue française*, Paris, Hachette, 1873–1874, **Domaine public** (public domain);
- **Application**: **78 599 entrées — consultation hors ligne** (78 599 entries, offline reading), and the author's credit.

The version line shows the installed version, for example **Version 1.1.2**.

## How to

### Look up a word

1. Open the app; you are on **Recherche**.
2. Check that the button at the right of the field shows the letters A–Z (**Recherche par mot**). If it shows the open book, tap it once.
3. Type the beginning of the word. Accents and capitals are not needed.
4. Tap the entry you want in the list.

If the word is not among the twenty entries shown, type more letters.

When a word has several entries (PRIME has eight), each one appears as its own card; the grammatical nature and the first lines of the definition tell them apart.

### Search inside the definitions

1. On **Recherche**, tap the search-mode button so that it shows the open book.
2. Type a word, or several words that follow each other in the text (for example the start of a proverb or of a quotation).
3. Tap an entry in the results.

Type whole words: the beginning of a word is not enough in this mode. A word written with œ or æ is typed with its joined letter (`cœur`). If you had already typed something before switching mode, the search is run again at once in the new mode.

### Go back to the search by word

Tap the search-mode button again so that it shows the letters A–Z.

### Empty the search field

Tap the cross at the right of the field. The word of the day comes back.

### Read the word of the day

Open the app with the search field empty: the word of the day is in the middle of the screen. Tap the card to read the whole article.

### Follow a cross-reference

In an article, tap an underlined word. The article it points to opens; the back arrow brings you back.

If the dictionary has no article for that word, the app says so with **Aucun article pour « … »** (no article for…), with the word it was looking for.

### Add an article to the favourites

1. Open the article.
2. Tap the star at the top right. It turns yellow.

### Remove an article from the favourites

1. Open the article (from **Favoris**, for example).
2. Tap the yellow star. It becomes an outline again and the article leaves the list.

### Find an article you read earlier

1. Tap **Favoris** in the bottom bar.
2. Tap the **Historique** tab.
3. Tap the article.

### Clear the history

1. Tap **Favoris** in the bottom bar, then the **Historique** tab.
2. Tap **Effacer l'historique** at the bottom. The list is emptied immediately and cannot be recovered.

You cannot remove a single line from the history.

### Copy an article to paste it elsewhere

1. Open the article.
2. Tap the copy button at the top right (**Copier l'article**).
3. Go to the other app and paste.

The copied text contains the headword, the grammatical nature, the body of the article and, under the line "Étymologie :", the etymology. The pronunciation and the 1878 supplement are not copied, and the text has no italics or other formatting.

### Put the word of the day on the home screen

1. On your home screen, open the list of widgets the way your launcher provides (often a long press on an empty area, then "Widgets").
2. Under **Le Littré**, choose the widget **Mot du jour**; its description is **Le mot du jour du Littré** (the Littré's word of the day).
3. Place it. It takes four cells by two and can be resized in both directions.

Tapping the widget opens the app.

## Settings

The app has no settings screen. There are only two things that vary:

| What | Choices | Default |
|---|---|---|
| Search mode (button at the right of the search field) | **Recherche par mot**, **Recherche dans les définitions** | **Recherche par mot**; it returns to it each time the app is restarted |
| Light or dark appearance | follows the phone's light or dark theme; nothing to set in the app | the phone's |

The text size, the typeface (Merriweather) and the colours cannot be changed in the app.

## Your data

Everything stays on the phone, in the app's private storage:

- the dictionary itself, unpacked at first start;
- your favourites;
- your history (the last hundred articles);
- the word of the day and its date.

Nothing goes over the network: the app does not have the Internet permission and cannot send or fetch anything. There is no account, no sync, no export, no import and no backup function in the app.

Uninstalling the app, or clearing its data in the phone's settings, removes the favourites and the history. The dictionary comes back with the app when you reinstall it; the favourites do not.

One thing is readable by other apps on the phone: the word of the day (the word, its nature and its definition). That is how Reader's Launcher displays it. Your favourites and history are not exposed.

## With the other apps

### Home-screen widget

The app offers one widget, **Mot du jour**. It shows the small heading **mot du jour**, the word, its grammatical nature and the first lines of its definition (three lines at most), in black on a white rounded card, whatever the theme of the phone. Tapping it opens the app on its main screen; to read the article, tap the word-of-the-day card there.

The widget and the app always show the same word. A word is drawn at random once a day, by whichever of the two is displayed first that day. The widget refreshes by itself about once an hour, so the new word appears within the hour after midnight.

### Reader's Launcher

Reader's Launcher has a **mot du jour** tile that reads the word from this app. The tile shows the word with **mot du jour** under it. Tapping it shows the whole definition and the etymology as plain text inside the launcher, with a row **open in Le Littré** (in French: **ouvrir dans Le Littré**) that opens this app. If Le Littré is not installed, the tile shows "Le Littré" instead of a word.

### What the app does not offer

The app does not appear in the share menu of other apps, does not appear in the text-selection menu, and does not open files.

## Limits

- French interface only.
- One dictionary only, in its 19th-century state: spellings, meanings and examples are those of 1873–1878.
- The search by word shows twenty entries at most.
- The search in the definitions shows fifty entries at most, finds whole words only, treats several words as an exact phrase, finds a word written with œ or æ only when it is typed with its joined letter, and does not look into the 1878 supplement.
- A few cross-references (26 of 14 820) point to a word the dictionary has no article for; the app says so instead of opening an article.
- The history keeps one hundred articles; older ones are dropped.
- Favourites cannot be sorted, grouped or exported.
- **Copier l'article** leaves out the pronunciation and the supplement.
- No audio pronunciation, no translation, no notes, no choice of text size.
- The widget is always black on white and opens the app, not the article.

## Messages and problems

| Message | Meaning | What to do |
|---|---|---|
| **Aucun résultat** | No entry matches what you typed in the current search mode. | Check the spelling; type fewer letters; check which mode the button shows. In **Recherche dans les définitions**, type œ and æ as joined letters. |
| **Aucun favori pour le moment** / **Appuyez sur l'étoile dans un article pour l'ajouter ici.** | You have not starred any article. | Open an article and tap the star. |
| **Aucun historique** / **Les articles consultés apparaîtront ici.** | No article opened yet, or the history was cleared. | Nothing; the list fills as you read. |
| **Aucun article pour « … »** (with the word looked for) | You tapped a cross-reference to a word the dictionary has no article for. | Go back to **Recherche** and type the word yourself: it may be entered under another spelling. |
| **Article copié dans le presse-papiers** | The article's text is on the clipboard. | Paste it where you want it. |
| The widget shows **Le Littré** and **mot du jour** instead of a word | The widget could not read the dictionary. | Open the app once, then wait for the widget's next refresh. |

### The word I want is not in the list

The search by word shows the first twenty entries in alphabetical order. Type more letters. Adjectives are entered with their feminine ending (ABAISSÉ, ÉE) and are found by typing the masculine.

### The word of the day is still yesterday's

The app picks the word when it displays the empty search screen. If the app stayed open overnight, close it and open it again, or type something in the search field and empty it.


# Clavier Plume

*Android 2.1.3*

## What it is

Clavier Plume is an Android keyboard for French and English, built first for writing French well: it restores elisions (l', d', qu', j'), accents and hyphenated forms, and applies French typography (curly apostrophe, non-breaking spaces, « » quotation marks). One key switches between the two languages, and the keyboard only learns a new word after you have used it three times. It is a modified version of the open-source FUTO Keyboard.

It works offline: the app has no Internet permission, no account and no advertising. It runs on Android 7.0 and later.

In this public edition, French correction comes from the dictionary and from the app's French rules; no neural language model is installed for French. A neural model for English, inherited from FUTO Keyboard, is built in and adds its proposals to the suggestion bar when you type in English. You can import other models from a file (see **Language models**).

It deliberately does not offer other languages than French (France, Switzerland, Canada) and English (US, UK), has no theme editor, does not sync anything, and does not update itself: updates come from the place you installed it from.

## First start

Open **Clavier Plume** from the app list. The first time, a walkthrough of eight steps appears. Each screen shows **Step 1 of 8** (and so on) with a progress bar. At the bottom: **Back**, **Skip** (steps 2 to 7) and **Next**; on the last step the button is **Done**. **Skip** changes nothing.

1. **Clavier Plume**: a presentation ("A French and English keyboard, built first for writing French well. One minute to set up."), a paragraph **What sets it apart**, and the line "Offline, no account, no ads: nothing leaves your phone."
2. **Your main language**: choose **Français** ("Curly apostrophe, non-breaking spaces, « » quotes") or **English** ("English spelling and punctuation"). The chosen card carries **Chosen ✓**. Below, **French of**: **Suisse**, **France** or **Canada**; and **English**: **US** or **UK**. The app pre-selects these from the phone's language and region. The main language "sets the typography and the toggle key. The other language stays available."
3. **Your layouts**: one layout **For French** (**QWERTZ (accents par appui long)**, **QWERTZ + é è à (Suisse)**, **AZERTY** or **QWERTY**) and one **For English** (**QWERTY** or **QWERTZ (accents par appui long)**), each with a preview. They are "suggested from the phone's region. Accents stay available with a long press on every layout." Tapping **Next** here installs these two languages with these layouts, replacing the previous list of languages.
4. **Two languages**: "Plume has a French and an English dictionary. How should they work together?" Choose **Robust — one language at a time** (pre-selected) or **Effortless — both languages at the same time**. "You can change this later in Settings → Languages."
5. **Enable the keyboard**: "Two Android settings, one tap each. You will come back here automatically."
   - **1. Allow Clavier Plume** ("In Android's keyboard list, turn on “Clavier Plume”") opens Android's keyboard list. Once done it reads **1. Clavier Plume allowed ✓**.
   - **2. Choose it as your keyboard** ("Pick “Clavier Plume” in the picker") opens Android's keyboard picker. Once done it reads **2. Keyboard in use ✓**.
   - "Next unlocks once both steps are done."
6. **Your theme**: tap a theme in the grid. "“Plume (auto)” follows the phone's light or dark mode. The Encre themes are high contrast." Below, the switch **Vibrate on key press** ("A light touch under the finger").
7. **The basics**: five reminders (**Switch language**, **Move the cursor**, **Read the suggestion bar**, **Learn and forget**, **Dictate**), then **Your contacts, optional**: "If allowed, the names in your address book are recognised and never corrected. They are read on the phone; nothing is sent." Tap **Allow contacts** to grant Android's contacts permission; the line then reads **Contacts recognised ✓**.
8. **Try it**: a text field ("Try typing here…") to test the keyboard. If your main language is French, the app suggests typing "jaime lordinateur voila" with a space after each word and watching the result. "Everything else lives in the settings, seven screens. This walkthrough stays available under About."

### Permissions

| Permission | When it is asked | What it is for |
|---|---|---|
| Microphone | The first time you tap the microphone | Dictation, done on the phone |
| Contacts | Only if you tap **Allow contacts** in the walkthrough | Recognising the names in your address book so they are not corrected |

The app also vibrates and reads and writes Android's personal dictionary. It has no Internet permission.

## The screens

### The keyboard

The keyboard has the letter rows, a shift key and a delete key, and a bottom row with the symbols key, the comma, the action key (emojis), the space bar, the period and the Enter key.

- **Long press on a letter** shows its accented variants and other characters.
- While a key is pressed, a balloon shows the character above your finger (setting **Key preview**).
- **Space bar, swipe sideways**: switches language (setting **Swipe on the space bar**).
- **Space bar, long press then slide**: the key labels fade and the keyboard becomes a trackpad that moves the cursor.
- **Delete key, press and slide left**: deletes characters as you slide.
- **Sliding over the letters** writes a word (setting **Swipe typing**).
- **Two spaces** insert a period followed by a space (setting **Double-space period**).

### The suggestion bar

Above the keys, from left to right:

- an arrow button that opens or closes the action row;
- the suggestions. "The middle word is applied on space. The word in quotes is exactly what you typed: tap it to keep it." A suggestion that comes from a neural model carries a small mark under the word;
- the **EN** / **FR** key, which shows the language you will switch to, and the microphone.

Other things can take the place of the suggestions:

- **↶ word**: just after an automatic correction, the bar starts with the word as you typed it, preceded by ↶. Tap it to undo the correction. It disappears as soon as you go on typing. The delete key right after a correction undoes it too.
- **Switch to English?** (or the other language): shown between two words after three consecutive words that belong to the other language and not to the active one. Tap it to switch; nothing is written. If you ignore it, it stays silent for the next twenty words. It only exists when exactly two languages are installed.
- the text you just copied, as a chip to paste it (setting **Copied text in the bar**);
- the fill-in proposals of your password manager, when the app you are typing in provides them.

**Long press on a suggestion** opens a question: "“word” — forget this learned word (the dictionary takes over again, it can be relearned later), or blacklist it for good?" with **Cancel**, **Forget (unlearn)** and **Blacklist**. On an emoji suggestion there is also **Disable emoji suggestions**.

**Long press on the EN / FR key** opens a list of your languages and layouts (tap one to use it), the other keyboards installed on the phone, and two buttons: **Switch Keyboard** (Android's keyboard picker) and **Settings**.

### The action row

The arrow at the left of the suggestion bar opens a second row with **All Actions** (three dots) followed by the favourite actions: **Undo**, **Redo**, **Text Editor**, **Clipboard Manager**, **Keyboard Modes**.

- **All Actions** shows every action as a grid: the favourites, **Emojis**, **Language switch key**, **Voice Input**, then **Settings**, **Paste from Clipboard**, **Theme Switcher**, **Cut to Clipboard**, **Copy to Clipboard**, **Select All**, **Arrow Up**, **Arrow Down**, **Arrow Left**, **Arrow Right**. Its title bar has an **Edit actions** button.
- **Edit actions** lets you drag each action into one of the groups **Action Key**, **Pinned Action(s)**, **Favorite Actions**, **More Actions**, **Hidden Actions**. Only one action can be the action key; pinning many actions shrinks the suggestion bar.

### Emojis

The action key next to the space bar opens the emoji panel: categories (**Recent**, **Smileys & Emotion**, **People & Body**, **Animals & Nature**, **Food & Drink**, **Travel & Places**, **Activities**, **Objects**, **Symbols**, **Flags**, **ASCII**), a **Search** field, a delete key and an **ABC** key to return to the letters. A long press on an emoji that has skin tones lets you choose one; the choice is remembered.

### Voice Input

The microphone opens the dictation panel. Speak; the panel shows **Try saying something**, then **Listening…**. Tap the panel to finish; the text is written at the cursor. Dictation also stops by itself when it detects silence. Recognition runs on the phone (Whisper).

### Clipboard Manager

Shows the clipboard history. While the history is off, the panel reads **Clipboard History Inactive** with the button **Enable Clipboard History**. Once on:

- tap an item to paste it; long press to pin or unpin it;
- the magnifier searches the history; the cross clears it (**Clear all unpinned items?** → **Clear**). When only pinned items remain it offers **Unpin**; when the list is empty it offers to **Disable** the history.

Up to 25 unpinned items are kept for 3 days; pinned items stay. Items marked as sensitive by the app they come from (password managers, private windows) are not kept.

### Keyboard Modes

A small panel with **Standard**, **One Hand**, **Split** (when the layout allows it) and **Float**, and the button **Resize Keyboard**. In resize mode, drag the handles, then **Apply**, or **Reset**. Size and mode are stored separately for portrait and landscape.

### Text Editor

A pad with four arrows, two toggles (Ctrl to move word by word, Shift to select) and keys to copy and paste.

### Theme Switcher

The grid of themes, above the keyboard, to change theme without leaving the app you are in.

### Settings home

Titled **Clavier Plume**, it lists seven screens: **Languages**, **Keyboard**, **Typing and correction**, **Action bar**, **Appearance**, **Backup**, **About**. The version number is shown under the list. At the very bottom, **Try typing here…** opens a field to test the keyboard.

### Languages

With exactly two languages installed, the card **Both languages** comes first, with two choices:

- **Effortless — both languages at the same time**: "Both dictionaries are consulted; the language you are typing in takes precedence. The EN/FR key still sets the layout and the typography."
- **Robust — one language at a time**: "Only the active language corrects; a word from the other language is treated as a typo until you switch."

Then one card per language with its **Layouts** (a cross removes a layout when there is more than one), **Add a layout**, and **Remove this language** (confirmation **Delete …?**, **Remove** / **Cancel**). When you have one language or more than two, each card has a checkbox **Suggestions in this language at the same time** instead of the **Both languages** card.

At the bottom, **Add language** opens **Select language to add**: French, French (Switzerland), French (Canada), English (US), English (UK). Choosing one opens **Select a layout to add** with a preview of each layout: besides the four of the walkthrough, Dvorak, Colemak, Colemak DH, BEPO, PC QWERTY and a few others.

### Keyboard

Sections **Size**, **Keys**, **Feedback** and **Space bar**; see Settings.

### Size and keyboard modes

Opened from **Keyboard** → **Size and keyboard modes** ("Resize, one-handed, floating, split"). The keyboard appears in resize mode. The screen reminds you that the same thing is available anywhere through the **Keyboard Modes** action, and has one entry: **Reset size settings** ("Tap to reset all sizes and modes for both portrait and landscape to default").

### Typing and correction

Sections **Correction**, **Typing**, **Neural model** and **Vocabulary**; see Settings. It leads to four screens:

- **Language models** ("Import a .gguf file and choose the model for each language"). The screen is titled **Transformer Models** and opens with the note "Neural language models. Clavier Plume's French/English model is imported from a .gguf file and assigned to a language." It lists the installed language models by language; tap one to see its details (in English only: **Details**, **Defaults**, **Actions**), make it the model of a language (**Set default model for …**), **Export to file** or **Delete**. Under **Dictation** it shows, for each of your languages, the dictation model in use: **Built-in model: Whisper multilingual 74** for French, **Built-in model: Whisper English 39** for English, or the name and size of a file you imported, with **Back to the built-in model**. **Precise dictation: download the 244 model (264 MB)** opens your browser on the download; "The 244 model is the most accurate but slower. Download it with the browser, then use Import a file below and choose the language." Last, under **Actions**: **Import a file (.gguf or .bin)**.
- **Learned words** ("Words the keyboard picked up, forget them in one tap"). Each line shows a word, its number of uses and its language, most used first. The star keeps the word for good (it goes to the personal dictionary and leaves this list); the cross forgets it. When empty: **No learned words yet.**
- **Personal dictionary** ("Your words and shortcuts"). First **For all languages** and one line per language with the number of words. Inside a list: **Add**, **Import a word list (txt, csv, Gboard, Hunspell, LibreOffice)**, then your words; tap a word to edit or delete it.
- **Ignored words** ("Words that are never suggested"). The switch **Block offensive words** ("Do not suggest potentially offensive words"), then **View and edit blacklisted words**: a field **Add to blacklist** with a + button, and the list, each word with a cross to remove it. When empty: **There are no blacklisted words.**

### Action bar

Sections **Action key**, **Voice input** and **Clipboard**; see Settings.

### Appearance

A grid of thirteen themes, each drawn as a small keyboard: **Plume (auto)**, **Plume clair**, **Plume sombre**, **Plume Ink (black on white)**, **Plume Ink inverted (white on black)**, **Plume Lavender**, **Plume Sage**, **Plume Nordic**, **Plume Terracotta**, **Plume Coquette**, **Plume Activist**, **Plume Sultry**, **Plume Nature**. Tap one to apply it. On Android 11 and later, a small round button at the bottom left shows or hides the keyboard so you can see the theme on it.

### Backup

Two entries: **Export configuration** ("Settings, personal dictionary and learned words to a file") and **Import configuration** ("Restore from an exported file").

### About

**Version 2.1.3** with **Tap to copy** (the message **Version copied** confirms), the lines "Clavier Plume is a modified version of FUTO Keyboard." and "Pierre Gallaz · developed with Claude Code", then:

- **Licences and credits** ("Contributors, third-party libraries"): **Translators**, **Layout contributors**, **Code contributors**, **3rd-party code & assets**.
- **Support FUTO Keyboard** ("Clavier Plume is built on FUTO Keyboard: pay for FUTO's license"): the **Payment** screen, titled **Pay for FUTO Keyboard**. The button **Pay (~$6.99 + tax)** opens FUTO's payment page in your browser; the money goes to FUTO, the makers of the keyboard Clavier Plume is built on. The screen also has **Already paid?** with **I already paid**, and **Other Options** → **Help** (FUTO's website). Nothing in Clavier Plume is locked if you do not pay.
- **Redo the walkthrough** ("Languages, layouts, theme, the basics").

### Import

When you choose a file to import, or open a keyboard file from a file manager (the app appears as **Import dictionary or model**), a screen titled **Import - …** names what the file is: **Voice Input Model**, **Transformer Model**, **Dictionary** or **Configuration Backup**. For a model or a dictionary: **Select the language to import for:** and the list of your languages. For a backup: the date of the file, a warning, and **Import** / **Cancel**.

## How to

### Switch between French and English

- Tap the **EN** / **FR** key at the right of the suggestion bar, or
- swipe sideways on the space bar, or
- tap **Switch to English?** (or the equivalent) when the bar offers it.

Switching changes the layout, the dictionary used for correction and the typography.

### Type French typography

In French (France and Switzerland), the keyboard does it for you:

- an apostrophe is written as a curly apostrophe (in English too);
- typing **;**, **!** or **?** after a word inserts a narrow non-breaking space before it, and **:** a non-breaking space. In Canadian French no space is added;
- the **"** key writes **«** followed by a non-breaking space, then, the next time, a non-breaking space followed by **»**;
- after "3e", "1er" and the like, the bar offers the ordinal forms (e, ème, er, re).

None of this applies in password, e-mail, web address and code fields, where no automatic space is added either. A web or e-mail address is not corrected.

### Accept or refuse a correction

1. Type the word. The middle suggestion is the one that will be applied when you type a space or a punctuation mark.
2. To keep exactly what you typed, tap the word in quotes at the left before typing the space.
3. If the correction has already been applied, tap the **↶** chip, or press the delete key once.

Undoing a correction counts as one use of the word you typed. Short everyday words (le, la, mes, mon, un, à, sur…; the, of, to, my…) are never replaced by another word.

### Move the cursor

Long press the space bar, then slide your finger. Or set **Swipe on the space bar** to **Move the cursor**. Or open **Text Editor** in the action row.

### Dictate

1. Tap the microphone in the suggestion bar.
2. The first time, allow the microphone.
3. Speak, then tap the panel to finish.

Dictation works in the language that is active on the keyboard.

### Get more accurate dictation

1. **Typing and correction** → **Language models** → **Precise dictation: download the 244 model (264 MB)**. Your browser downloads the file.
2. Back on the same screen, tap **Import a file (.gguf or .bin)** and pick the downloaded file.
3. On the **Import - Voice Input Model** screen, tap the language it should serve.

To go back: **Back to the built-in model** on the same screen.

### Make the keyboard learn a word, or forget one

- A word that is not in the dictionary is kept after its third use. A word you delete with the delete key right after typing it does not count.
- To keep a learned word for good: **Typing and correction** → **Learned words** → the star.
- To forget one: the cross on the same screen, or long press the word in the suggestion bar → **Forget (unlearn)**. It can be learned again.
- To ban a word: long press it in the suggestion bar → **Blacklist**, or add it in **Ignored words**.
- To stop learning altogether: turn off **Learn my words**.

### Add a word or a shortcut to the personal dictionary

1. **Typing and correction** → **Personal dictionary**.
2. Tap **For all languages** or a language.
3. Tap **Add**.
4. Fill **Word:** ("Type a word") and, if you want, **Shortcut:** ("Optional shortcut"): typing the shortcut will propose the word.
5. Tap **OK**.

To change or remove a word, tap it: **Edit word**, then **OK** or **Delete**.

### Import a list of your words

1. **Typing and correction** → **Personal dictionary** → a language (or **For all languages**).
2. Tap **Import a word list (txt, csv, Gboard, Hunspell, LibreOffice)** and pick the file.
3. A window **Import** reports "… added, … already known, … rejected".

Accepted: a plain text file with one word per line; a CSV or tab-separated file (the first column is the word); a Gboard dictionary export (zip); a Hunspell or LibreOffice .dic file. Words already in the built-in dictionaries or in your personal dictionary are counted as already known.

### Add a language or a layout

1. **Languages** → **Add language**, pick the language, then the layout.
2. For a second layout of a language you already have: **Add a layout** on its card.

With several layouts, the EN / FR key goes through them in turn; a long press on it shows the whole list.

### Change the size or use one hand

Open the action row → **Keyboard Modes**, then **Standard**, **One Hand**, **Split** or **Float**; **Resize Keyboard** to change the height. Or go through **Keyboard** → **Size and keyboard modes**.

### Use the clipboard history

1. Open the action row → **Clipboard Manager** → **Enable Clipboard History** (or turn on **Clipboard history** in **Action bar**).
2. From then on, what you copy appears there. Tap to paste, long press to pin.

### Put the language key or the emojis where you want

In **Action bar**: **Action key next to the space bar** shows or hides the key left of the space bar; **Language switch key** puts the language switch there instead of the emojis. For anything else, open the action row → **All Actions** → **Edit actions** and drag the actions between the groups.

### Save your configuration and restore it

To save:

1. **Backup** → **Export configuration**.
2. Choose where to save the file (its proposed name starts with "FUTOKeyboardSettings_" and ends with ".backup").
3. Wait for **Exporting configuration…** to finish ("Please do not close this menu until the process is completed (5 to 10 seconds)").

To restore, on the same phone or another one:

1. **Backup** → **Import configuration** and pick the file.
2. Read the warning, then tap **Import**.

Importing replaces everything: settings, personal dictionary, learned words, imported files.

### See the walkthrough again

**About** → **Redo the walkthrough**. The walkthrough starts again from its first step with its own proposals, not your current choices: use **Skip** on the steps you do not want to change. **Next** on **Your layouts** reinstalls the two languages and layouts shown there, and **Next** on **Two languages** applies the mode shown there.

## Settings

### Languages

| Setting | Choices | Default |
|---|---|---|
| **Both languages** (two languages installed) | **Effortless — both languages at the same time** / **Robust — one language at a time** | Robust |
| **Suggestions in this language at the same time** (one language, or more than two) | Checked / unchecked, per language | Unchecked |

### Keyboard

| Setting | What it changes | Default |
|---|---|---|
| **Number row** | "Show 1234567890 above the letters" | Off |
| **Key preview** | "Show the character above the key while pressing" | On |
| **Long-press hints** | "Small character in the corner of the keys" | Off |
| **Long-press duration** | How long to hold a key for a long press, 100 to 700 ms | 300 ms |
| **Vibration on key press** | Vibrates at each key | On |
| **Vibration duration** | Shown only when vibration is on: **System**, or up to 100 ms | **System** |
| **Sound on key press** | Plays a sound at each key | Off on a phone, on on a tablet |
| **Swipe on the space bar** | **Nothing**, **Move the cursor** or **Switch language** | **Switch language** |

### Typing and correction

| Setting | What it changes | Default |
|---|---|---|
| **Auto-correction** | "Correct the word when you type a space or punctuation" | On |
| **Show suggestions** | "Word suggestions above the keyboard" | On |
| **Emoji suggestions** | Offers emojis among the suggestions | On |
| **Auto-capitalisation** | "Capital letter at the start of each sentence" | On |
| **Double-space period** | "Two spaces insert a period followed by a space" | On |
| **Swipe typing** | "Slide your finger over the letters to type a word" | On |
| **Learn my words** | "Suggest words you type that are not in the dictionary" | On |
| **Block offensive words** (in **Ignored words**) | "Do not suggest potentially offensive words" | On |

With auto-capitalisation on, no capital is put after the abbreviations ex., max., op., cf., p., pp., e.g. and i.e.

### Action bar

| Setting | What it changes | Default |
|---|---|---|
| **Action key next to the space bar** | Shows the key left of the space bar; its line names the action it carries (**Emojis**). Turning it off moves that action to the action row. | On |
| **Language switch key** | "Replaces the emoji key with a language key"; the emojis go to the action row. Turning it off again brings the emoji key back and puts the language switch in the action row. Shown only while the action key is on. | Off |
| **Microphone key** | "Dictate text from the suggestion bar". Off: dictation is found in **All Actions**. | On |
| **Copied text in the bar** | "Offer the last copied text as a suggestion" | On |
| **Clipboard history** | "Keep copied items in the clipboard panel" | Off |

### Appearance

One choice among the thirteen themes. The default is **Plume Lavender**. **Plume (auto)** follows the phone's light or dark mode.

## Your data

Everything stays on the phone. The app cannot use the network: it has no Internet permission. The two links it contains (the 244 dictation model and FUTO's payment page) open in your browser, not in the app.

What the keyboard keeps:

- **Your settings**, languages, layouts and theme.
- **The personal dictionary**: your words and shortcuts are stored in Android's own personal dictionary, which is shared across the system.
- **Learned words and word counts**: the keyboard counts each word you validate, per language (words of 2 to 40 letters without digits, at most 50,000 entries), and remembers which words follow which, to rank its suggestions. Nothing is counted in password, e-mail, web address and code fields.
- **The clipboard history**, only if you turned it on.
- **Imported files**: dictation models, language models, dictionaries.
- **Contact names**, read from your address book if you allowed it; they are not copied elsewhere.

**Export** puts all of the above (except the contacts) in one file that you save where you want; the app sends it nowhere. Keep this file private: it contains your words and your clipboard. **Import** replaces the current data with the file's. A file made by a newer version of the keyboard shows a warning and may not import properly.

There is no sync and no conflict handling: one phone, one configuration.

Uninstalling the app removes its settings, learned words, clipboard history and imported files from the phone. The app also lets Android's own backup include its data, where the phone has such a backup.

## With the other apps

- Clavier Plume works in every app that has a text field. It offers no home-screen widget.
- It also registers with Android as a spell checker, under the name **Clavier Plume — correcteur**.
- It opens files: a dictionary, a dictation model, a language model or a configuration backup opened from a file manager can be handed to **Import dictionary or model**.
- It shows the fill-in proposals of your password manager in the suggestion bar.
- From the clipboard history it can paste an image into apps that accept images; otherwise it says **App does not support image insertion**.

## Limits

- Languages: French (France, Switzerland, Canada) and English (US, UK) only.
- No French neural language model is included; the keyboard does not say where to obtain one.
- Language models must be .gguf files made for this keyboard; dictation models are .bin files; dictionaries are compiled .dict files, not word lists.
- A word list of more than 20,000 words is refused. Entries with a space or longer than 48 characters are rejected.
- The clipboard history keeps 25 unpinned items for 3 days; these figures cannot be changed.
- The themes cannot be edited and no theme can be added from the settings.
- The model screens (details, export, delete) are in English only.
- The export file keeps the name "FUTOKeyboardSettings_…".
- No automatic updates from within the app.

## Messages and problems

| Message | Meaning and what to do |
|---|---|
| **Next unlocks once both steps are done.** | In the walkthrough, turn the keyboard on in Android's list, then choose it in the picker. |
| The walkthrough reappears when you open the app | The keyboard was turned off or replaced by another one. The app reopens on **Two languages**; tap **Skip** to reach **Enable the keyboard** and redo the two steps. (**Next** on **Two languages** would apply the choice shown on that screen.) |
| **Switch to English?** (or another language) | The last three words belong to the other language. Tap to switch, or keep typing to ignore. |
| **… added, … already known, … rejected** | Result of a word list import. Rejected lines contained a space, were too long or were headers. |
| **This file has … words — more than a personal list (limit 20000). Nothing imported.** | The file looks like a whole language dictionary. Import a shorter list. |
| **Error: Shortcut may not start with symbol** | Begin the shortcut with a letter or a digit. |
| **Error: This file could not be recognized. It may be invalid or it may have been corrupted. Try re-downloading it, or try a different file.** | The file is not a model, a dictionary or a backup of this keyboard. Check that the download finished. |
| **Error: This file appears to be a source wordlist (_wordlist.combined) instead of a compiled dictionary (.dict) file.** | For a list of your own words, use **Import a word list** in **Personal dictionary** instead. |
| **This file appears to be intended for a language (…) which is not enabled in settings** | Add that language first, or choose one of your languages knowingly. |
| **Are you sure you want to import this configuration backup? This will replace all of your settings, personal dictionary (system-wide), learned dictionary words, any imported resources, and more. If you’re unsure, make another backup before this.** | Importing overwrites. Export the current state first if in doubt. |
| **This configuration backup was created by a newer version of FUTO Keyboard, and it might not import properly. Try updating FUTO Keyboard first.** | The backup comes from a newer version of the keyboard. Update Clavier Plume, then import. |
| **Importing configuration… Please do not close this menu until the process is completed (5 to 10 seconds)** | Wait. |
| **Clipboard History Inactive** | Tap **Enable Clipboard History** to start keeping what you copy. |
| **Device Locked** — "Please unlock your device to access clipboard history" | The clipboard history and the theme settings are not available on the lock screen. |
| **Clipboard Error** | The history could not be read or saved. **Retry**, or **Delete** the history (all items are lost). |
| **App does not support image insertion** | The app you are typing in does not accept pasted images. |
| **Please go to Permissions, and enable Microphone permission to use voice input** | The microphone was refused. Tap the line to open the app's Android settings and allow the microphone. |
| **No audio detected, is your microphone blocked?** | Check that the microphone is not switched off in Android's quick settings. |
| **Error loading model. It may be corrupted or incomplete. Try reverting it to default or downloading again.** | The imported dictation model is damaged. **Back to the built-in model**, or download and import it again. |
| "Unable to load Transformer model for …, it may be corrupted or unsupported." | The language model of that language cannot be used; the keyboard carries on with the dictionary. Delete the model or choose another in **Language models**. |
| "This model is damaged, its metadata could not be loaded. It may be corrupt or it may not be a valid model file." | Delete the model from its screen. |
| **No learned words yet.** | Nothing has been learned yet: a new word appears here after its third use. |
| **There are no blacklisted words.** | The list of ignored words is empty. |

If a word you want keeps being corrected: tap the word in quotes to keep it; after three uses it is learned. To have it at once, add it to the **Personal dictionary**.

If a learned mistake keeps being proposed: long press it in the suggestion bar → **Forget (unlearn)**.

If French words are corrected while you write in English (or the reverse): switch language with the EN / FR key, or choose **Effortless — both languages at the same time** in **Languages**.


# Funky's 2P Games

*Android 1.36*

## What it is

Funky's 2P Games is a collection of 16 games for two players. You play them face to face on a single phone, each player using one half of the screen or taking turns.

Every game carries its own rules behind a **?** button. There are no ads, no accounts and no purchases.

The app never plays against you: there is no computer opponent and no solo mode. It keeps no scores from one game to the next. Its texts are in English only.

## First start

The app asks for nothing: no permission, no account, no server to enter. It opens straight on the menu of games.

It works without any connection.

## The screens

### The menu

The menu is titled **2 Player Games**. Next to the title is a speaker button that switches the background music on or off.

Below, sixteen coloured cards in two columns, one per game: Tennis, 4 in a Row, Pool, Memory, Word Clash, Air Hockey, Tank Wars, Carrom, Mini Golf, Star Clash, Caro, Awalé, Duck-Day Chess, Hangman, Reversi, Horse Jump. Scroll to see them all. Tap a card to open the game.

At the bottom of the list, a line of credits: **Pierre Gallaz · developed with Claude Code**.

### The game screen

Every game uses the same frame. The bar at the top holds, from left to right:

- **◀**: leaves the game and returns to the menu, at once and without confirmation. The game in progress is lost.
- the name of the game;
- **?**: opens the rules of the game; tap **?** again, **Got it** or **×** to close them. The game is not paused while the rules are shown.
- the speaker button: music on or off, the same setting as on the menu;
- the status: whose turn it is, the score, or the result. In turn-based games it reads for example **P1's turn**, **Red's turn**, **Black's Turn**.

The rest of the screen is the playing area. **P1** is player 1 and **P2** is player 2. While a game is open the screen stays lit.

In several turn-based games (Memory, Word Clash, Tank Wars, Carrom, Pool, Mini Golf, Hangman) a banner **Player 1, your turn!** or **Player 2, your turn!** flashes for a second when the turn passes.

### The end-of-game panel

When a game ends, a panel covers the playing area with the result (for example **P1 wins!**, **Draw!**) and often the final score. Under it, a button starts a new game: **Rematch** in most games, **Restart** in Caro, **New Game** in Hangman. The **×** in the top right corner closes the panel without starting again.

Pool and Mini Golf show the result without a button: to play again, go back to the menu with **◀** and reopen the game.

## How to

### Start a game

1. On the menu, tap the card of the game. The game opens at once.
2. Put the phone between you. In games played on two halves, P1 has the bottom half and P2 the top half (in Horse Jump, P1 has the top lane).

### Read the rules of a game

1. Open the game.
2. Tap **?** in the top bar.
3. Tap **Got it** to close.

### Play again

Tap the button of the end-of-game panel (**Rematch**, **Restart** or **New Game**).

In Tank Wars, **Rematch** reloads the whole app and brings you back to the menu; reopen the game from there.

### Leave a game

Tap **◀**. The game in progress is lost.

### Switch the music off

Tap the speaker button, on the menu or in the top bar of a game. Tap again to switch it back on.

### Tennis

P1 is the red paddle at the bottom, P2 the blue paddle at the top.

- Aim: send the ball past your opponent's paddle.
- Play: slide your finger on your half of the screen (the strips marked **slide here**); your paddle follows it sideways. The ball bounces off the side walls and gets a little faster at every paddle hit. After a point the ball restarts from the centre towards the player who lost the point.
- Power-ups: a coloured disc appears on the court from time to time and vanishes after about ten seconds. When the ball touches it, the player who last hit the ball gets it. **BIG**: your paddle grows. **TINY**: the opponent's paddle shrinks. The lightning bolt: the ball speeds up at once. **\~\~**: slow motion. **?**: the ball becomes almost invisible. **U**: the ball curves towards your paddle. **\~**: the paddles shake. **2x**: a second ball comes into play, and each ball that gets through counts as a point. A short text such as **+Paddle → P1** names the effect and who received it.
- End: the first to 5 points wins. The status shows **P2: 0 | P1: 0**.

### 4 in a Row

Red plays first; the second player is Yellow.

- Aim: line up four of your discs, across, down or diagonally.
- Play: tap any cell of a column; your disc falls to the lowest free cell. The turn passes.
- End: **Red wins!** or **Yellow wins!** at the first line of four; **Draw!** if the board (7 columns, 6 rows) fills up.

### Pool

P1 shoots first.

- Aim: pocket all the balls of your group, then the 8-ball.
- Play: put your finger on the table and pull away from the cue ball (the white one): the ball leaves in the direction opposite to your finger, and the further you pull, the stronger the shot. A dashed line shows the direction; the view zooms out when you pull far. Release to shoot.
- Groups: the first ball pocketed decides. Balls 1 to 7 are **solid**, 9 to 15 **stripe**; the player who pockets first gets that group, the other player gets the other one. The status then reads for example **P1's shot P1:solid P2:stripe**.
- Turn: you shoot again if you pocketed a ball of your group; otherwise the turn passes. If you pocket the cue ball, it returns to its starting spot and the turn passes.
- End: pocket the 8-ball after all your balls and you win. Pocket it before and you lose: **P1 pocketed 8-ball early! P2 wins!**

### Memory

32 cards, 16 pairs of fruit.

- Aim: collect more pairs than your opponent.
- Play: tap two cards to turn them over. If they match, they stay face up, you score 1 and play again. If not, they turn back and the turn passes.
- End: when all pairs are found, the player with the most pairs wins; equal scores give **Draw!**. The status shows **P1: 0 P2: 0** and whose turn it is.

A double tap on the empty space around the cards replaces one of the fruits with a surprise picture until the end of the game.

### Word Clash

The game first asks **Choose Language**: **English** or **Français**.

- Aim: score more points than your opponent on a shared crossword.
- The board: a small crossword of hidden words, all made from the seven letters shown on the wheel below. The top line shows **P1:** and **P2:** scores and the number of tries left; under the grid, the count of words found (for example **2/6 words**).
- Play: put your finger on a letter of the wheel and slide to the next ones to spell a word of at least three letters; slide back to the previous letter to remove the last one; lift your finger to submit. A word of the grid fills in with your colour (P1 red, P2 blue) and scores its number of letters. A valid word that is not in the grid is a bonus word: 1 point, listed after **Bonus:**.
- Tries: you have 3 tries per turn. Every submitted word, right or wrong, uses one. **Hint (uses 1 try)** reveals one random letter of the grid and uses one too. After the third try the turn passes.
- The round arrow in the middle of the wheel shuffles the letters; it costs nothing.
- End: when every word of the grid is found and the current turn is over, the highest score wins; equal scores give **It's a tie!**

### Air Hockey

P1 is the red mallet at the bottom, P2 the blue mallet at the top.

- Aim: push the puck into the opponent's goal, the dark slot in the middle of their end.
- Play: drag your mallet with your finger; it cannot leave your half. The speed of your mallet matters: a fast swipe smashes the puck (sparks, screen shake), a gentle one taps it. After a goal the puck returns to the centre.
- End: the first to 5 goals wins. The status shows **P2: 0 | P1: 0**.

### Tank Wars

P1 is the red tank on the left, P2 the blue tank on the right. Each tank starts with 100 HP.

- Aim: destroy the opponent's tank.
- Play: on your turn, drag anywhere above the control area: left or right changes **Angle**, up or down changes **Power** (up for more). The barrel moves as you drag. Then tap the red **FIRE** button.
- The shell is pulled by gravity and pushed by the wind. The wind (**Wind:** with an arrow and a strength) is drawn at the start and stays the same for the whole game.
- The explosion digs a crater in the ground and damages any tank nearby, yours included: up to 40 HP for a direct hit, less the further away it lands. A shell that leaves the screen does nothing.
- End: a tank at 0 HP is destroyed and the other player wins.

### Carrom

P1 plays White from the bottom baseline, P2 plays Black from the top one. The board holds 9 white pieces, 9 black pieces and the red Queen in the centre, with a pocket in each corner.

- Aim: pocket all nine pieces of your colour before your opponent.
- Play: touch the coloured strip along your baseline (marked **‹ ›**) to slide the striker left or right. Then touch outside the strip, or keep your finger down and drag off it, and pull back like a slingshot: the striker leaves in the direction opposite to your finger. A dashed line shows the direction and a bar under the board shows the power. Release to flick.
- Your colour pocketed: 1 point each, and you play again.
- The opponent's colour pocketed: they score the point, and your turn ends unless you also pocketed one of yours.
- The Queen: pocket her and you keep the turn. If you pocket one of your pieces in the same shot or in the next one, you score 3 more; the status shows **Cover Queen!** while you owe that shot. If you miss it, the Queen returns to the centre.
- Foul: if the striker falls in a pocket, your turn ends, a pending Queen returns to the centre and, if you had already pocketed pieces of your colour, one of them returns to the centre and you lose 1 point.
- End: the first player with no piece left on the board wins. If you pocket your opponent's last piece, they win.

### Mini Golf

Six holes.

- Aim: finish the six holes in fewer strokes than your opponent.
- Play: P1 plays the hole until the ball is in, then P2 plays the same hole from the same tee, then both move to the next hole. To putt, put your finger down and pull away from the ball: the ball leaves in the direction opposite to your finger, and the further you pull, the stronger the putt. Dots show the direction and a small bar the power; the view zooms out when you pull far. Release to putt. The ball bounces off the wooden walls.
- The screen shows **Hole 1/6**, the current player with their strokes, and both totals.
- End: after the sixth hole the lower total wins; equal totals give **Draw!**

### Star Clash

P1 is the red ship at the bottom, P2 the blue ship at the top. A formation of aliens sits between them.

- Aim: be the last ship standing.
- Play: slide your finger on your half (the strips marked **P1 — slide here** and **P2 — slide here**); your ship follows it sideways and fires by itself as long as your finger is down.
- Lives: each ship has 3 hearts. Alien shots cost one heart, and so does a shot from the other ship that gets through. Small barriers in front of each ship stop shots and crumble; they are rebuilt at each wave.
- Score: 10, 20 or 30 points per alien depending on its row. Kills in a row build a multiplier (3 kills: x2, 5: x3, 8: x4); taking a hit resets it.
- Glowing aliens give an effect for a few seconds to the player who shoots them: a lightning bolt (faster fire), an explosion (bigger shots), a snail (slow ship and slow fire), scissors (short-range shots).
- Every 100 points you score, a red alien dives at your opponent, firing; shooting it is worth 50 points. Your shots cancel alien shots they meet.
- When all the aliens of the formation are destroyed, a new wave arrives (**Wave 2**, and so on). From wave 5, aliens move and fire much faster.
- End: the game stops as soon as one ship loses its last heart; the other player wins, whatever the scores.

### Caro

A board of 13 by 13. Black plays first.

- Aim: line up exactly five stones, across, down or diagonally.
- Play: tap an empty point to place a stone. The turn passes.
- A line of six or more does not win. A line of five does not win either if the opponent blocks both ends, or blocks one end while the other touches the edge of the board.
- End: **Black Wins!** or **White Wins!**, with the winning stones highlighted; **Draw!** if the board is full. The button to play again is **Restart**.

### Awalé

Twelve pits with 4 seeds each. P1 owns the bottom row, P2 the top row; each pit shows its number of seeds. When the phone is held upright, the board is drawn turned a quarter turn: P1's row is then on the left and P2's on the right.

- Aim: capture at least 25 seeds.
- Play: tap one of your pits that holds seeds. Its seeds are sown one by one in the following pits, counter-clockwise, skipping the pit they came from.
- Capture: if your last seed lands in one of the opponent's pits and brings it to 2 or 3 seeds, you capture them, and also those of the preceding opponent pits, one after the other, as long as they hold 2 or 3.
- End: the game stops when a player reaches 25 seeds, or when the player whose turn comes has no seed left on their side; in that case the player who just moved takes all the seeds that remain. The higher score wins.

### Duck-Day Chess

A full game of chess, White first, with two ducks added.

- Aim: checkmate the opponent's King.
- A turn has two steps. First, move: tap one of your pieces (dots mark where it can go, a ring marks a capture), then tap the destination. Castling and en passant captures are available; a pawn reaching the last row opens **Promote:** with Queen, Rook, Bishop and Knight. Second, the status asks you to place the Yellow Duck: tap any empty square.
- The Yellow Duck blocks its square: no piece can stop on it or pass through it. There is a single Yellow Duck: it stays in place while the other player chooses their move, is lifted when that move is played, and is placed again by the player who just moved.
- The Red Duck appears by itself and jumps to a random empty square after each Yellow Duck is placed. It blocks its square in the same way.
- The laser: every 5 moves (counting both players' moves), the Red Duck fires at one piece next to it, chosen at random, of either colour, and removes it. The gauge above the board, on the right, fills square by square until the shot.
- Kings are safe from the laser during the first 25 moves of each player. After that a skull appears next to the gauge, and a King hit by the laser loses the game at once.
- If the ducks leave a player with no possible move although they are not in check, the app moves or removes a duck by itself; the log reads **Canard de Secours!**
- The log under the board lists the last moves and events; the square of a King in check glows red.
- End: checkmate (**White wins by checkmate!**), a King removed by the laser (**White wins — King vaporized!**), or a draw by stalemate (**Draw by stalemate!**).

### Hangman

The app picks the word; it is a French word if the phone is set to French, an English word otherwise.

- Aim: have the most points when the word is complete.
- Play: on your turn, tap a letter. If it is in the word, you score 1 point for each place it fills and you play again. If it is not, a part of the body is added to the gallows (**Wrong: 1/6**) and the turn passes. Letters already tried are greyed out and listed after **Used:**.
- End: when the word is complete, the player with more points wins; equal points give **It's a tie!**. At the sixth wrong letter the panel shows **Hanged!** with the word, and nobody wins. **New Game** draws a new word and resets both scores.

### Reversi

A board of 8 by 8 starting with two black and two white discs. Black plays first.

- Aim: have the most discs of your colour at the end.
- Play: tap one of the squares marked with a small dot; these are your legal moves. Your disc must trap one or more straight lines of opposing discs between itself and another of your discs; all the trapped discs flip to your colour.
- If a player has no legal move, the status reads for example **White passes — no legal move** and the other player moves again.
- The status shows whose turn it is and the count, black first (**Black's turn 2–2**).
- End: when neither player can move, the larger count wins (**Black wins 40–24**); equal counts give a draw.

### Horse Jump

The start screen is titled **EQUINE EDGE**. P1 rides the white horse in the top lane, P2 the brown horse in the bottom lane.

- Aim: stay in the race longer than your opponent.
- Play: tap anywhere to start (**Tap to start!**). Then tap your half of the screen to make your horse jump. Both lanes receive the same obstacles: hurdles, and holes in the ground once fifteen obstacles have been cleared. The pace quickens as the count of cleared obstacles rises.
- With a keyboard attached, P1 jumps with the keys on the left (Q, W, A, S, Space and their neighbours) and P2 with those on the right (P, O, L, K, Enter, the arrows and their neighbours).
- End: the first horse that hits a hurdle or falls in a hole loses (**P1 Wins!** or **P2 Wins!**); if both fall at the same instant, **Dead Heat!**. The panel shows **Hurdles cleared:** with the count.

## Settings

The app has a single setting.

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| Speaker button (menu and top bar of a game) | Background music during the games | on, off | on |

The choice is remembered. The music plays while a game is open and stops when you return to the menu; switching it on from the menu starts it at once. The sound effects of the games are not affected by this button; there is no switch for them.

The language of the words in Word Clash is chosen at the start of each game and is not remembered; the button that matches the phone's language is highlighted.

## Your data

On the phone, the app stores one thing: whether the music is on or off. It keeps no scores, no history of games, no names. Uninstalling the app removes that setting; there is nothing else to remove.

The app sends nothing over the network: it works without any connection.

## Limits

- Two players, always: no computer opponent, no solo mode, no more than two.
- No scores or statistics are kept after you leave a game.
- A game cannot be paused or saved; **◀** ends it.
- The interface is in English only. Word Clash has English and French words; Hangman follows the phone's language (French or English). French words are written without accents.
- Duck-Day Chess has no clock, no draw offer and no resign button.
- Pool and Mini Golf have no button to play again at the end.

## Messages and problems

| Message | Meaning | What to do |
|---|---|---|
| **White passes — no legal move** (or **Black passes**) | Reversi: that player cannot move; the other plays again. | Keep playing. |
| **Cover Queen!** | Carrom: you pocketed the Queen and must pocket one of your pieces with this shot to keep her. | Aim at one of your pieces. |
| **P1 pocketed 8-ball early! P2 wins!** | Pool: the 8-ball went in before all the balls of the shooter's group. | The game is lost; reopen Pool to play again. |
| **Canard de Secours!** | Duck-Day Chess: the ducks left a player without a move, and the app moved or removed one. | Keep playing. |
| **Move 25 reached — Kings are no longer immune to the Red Duck laser!** | Duck-Day Chess: from this point the laser can remove a King. | Keep your King away from the Red Duck when the gauge is nearly full. |
| **Hanged!** | Hangman: six wrong letters; nobody wins. | Tap **New Game**. |

After **Rematch** in Tank Wars you are back on the menu: this is how the game restarts; open Tank Wars again.




<!-- Meditation -->


# Retreat Timer

*Android 1.13.1*

## What it is

Retreat Timer rings singing-bowl bells at the times of day you set, every day, so that a meditation retreat keeps to its schedule with no one at the bell. Each time rings three bells or one, and recorded talks can be scheduled to play at a set time exactly like the bells. What makes it different is that it is built to ring whatever the phone is doing: screen locked, hours of deep sleep, a restart during the night. A light on the first screen turns green when the phone is ready to be left alone.

The app has no countdown timer, no sitting of X minutes, no statistics, no account, no ads and no tracking. It uses the network for one thing only: downloading talks when you ask for them.

The app exists in English only; there is no language setting. It works on Android 8.0 and later, in portrait.

## First start

On Android 13 and later, the app asks once for permission to show notifications. The notification is where the playback controls appear while a bell or a talk is playing, and where a download or the speaker keep-alive shows that it is running.

There is no account and no server to enter. The app opens on the **Schedule** tab, under the title **Retreat Timer** and the line **Bells and talks, on time, all day — even with no one present.**

When nothing is set up yet you see:

- an amber card, **⚠ One step left for guaranteed playback**, with the text **Tap below so Android never pauses the app. Without this, deep sleep could delay playback.** and one or two buttons: **Allow background running** and, if you refused notifications, **Allow notifications**;
- the **Bell sound** card, with **Singing bell** chosen;
- the **Levels** section, with **Bells** and **Talks** both at **100%**;
- the **Keep Bluetooth speaker awake** card, switched off;
- the line **Nothing scheduled yet — add a bell below or schedule a talk.**;
- the button **Add first bell**.

The one thing to do on the first day is to tap **Allow background running** and accept the phone's request to stop optimising the battery for this app. Once this is done and notifications are allowed, the card turns green: **✓ Ready — bells and talks will play on time**. The card checks again about every half minute, so it can take a moment to change.

## The screens

The app has two tabs, **Schedule** and **Library**, under the title. A player bar appears at the bottom of both whenever a scheduled bell or a talk is playing.

### Schedule tab

From top to bottom:

**The readiness card.** Green, with **✓ Ready — bells and talks will play on time** and **The phone can be locked or asleep all day. Keep it charged and everything plays without anyone present.**, when the app is exempt from battery optimisation and notifications are allowed. Amber, with **⚠ One step left for guaranteed playback**, otherwise. **Allow background running** opens the phone's request to exempt the app from battery optimisation; **Allow notifications** opens the app's notification settings in the phone. Each button is shown only while its step is missing.

**Bell sound.** One line per sound, each with a round selector on the left and **Preview** on the right:

- **Singing bell**
- **Tibetan bowl (E♭)**
- **Gong bowl**
- **Satipanya**
- **enpleineconscience.ch**

Tap the selector to make that bowl the sound of every bell. Tap **Preview** to hear its three-strike recording; previewing does not change the choice. Below the five bowls is the line **Your own sound** with **Choose file**. Once you have chosen a file, the line carries the file's name, a play button to hear it once, and **Change** to pick another file; its selector becomes usable. Two notes close the card: **Your own sound is an mp3 or wav file from the phone; it stands in for the single strike, and a three-bell slot plays it three times over.** and **The chosen bowl rings out fully between strikes. Whether a slot rings three times or once is set on the bell itself — tap its time.**

**Levels.** The text reads **Overall loudness follows the phone's volume — and, over Bluetooth, your speaker's. These only trim bells and talks down from there, so the two stay matched through an unattended day.** Two cards follow:

- **Bells**: a percentage, a **Test bell** button and a slider from 5% to 100%. **Test bell** rings one strike of the chosen sound at the level shown. If you move the slider while it rings, you hear the change at once. The note reads **Trims the bells down from the phone/speaker volume. 100% = full. Test rings one bell — enough to judge the level without sitting through three.**
- **Talks**: the same, with **Test talk**. It plays the next talk on the schedule, or, if no talk is scheduled, the first talk of the Library; the note names it: **Trims talks independently of the bells, so speech and bowl strikes stay matched. Test plays “…”; adjust while it runs.** With no talk in the app the button is greyed and the note reads **Trims talks independently of the bells. Add a talk in the Library tab to test it.**

**Keep Bluetooth speaker awake.** A switch, off by default. Under the title, one line says whether a wireless speaker is there: **✓ A Bluetooth speaker is connected** or **No Bluetooth speaker connected right now**. The explanation reads: **Portable speakers often disconnect after a few minutes of silence, so the next bell comes faintly from the tablet instead. This holds the link open with a silent keep-alive signal between bells — the same trick as the “silence + bells” loops centres play. Turn it on only when using an external speaker, and keep the tablet charged.**

**The next line.** **Next at 06:30 — three bells — in 1h 5min**, with a small bell symbol before the words **three bells** or **one bell**, or a headphones symbol before the title of a talk. Under one hour it reads **in 12min**. With nothing switched on in the schedule it reads **Nothing scheduled yet — add a bell below or schedule a talk.**

**The schedule.** One card per entry, sorted by time of day. Bells and scheduled talks are in the same list. Each card shows:

- the time, on 24 hours, in large type. Tap it to change the time (and, for a bell, three bells or one);
- for a bell, a badge **×3** or **×1** beside the time;
- under the time, **Three bells** or **One bell** after a bell symbol, or the talk's title after a headphones symbol;
- a play button: for a bell, it rings that bell now, three strikes or one, as a preview; for a talk, it starts the talk in the player bar;
- a switch: off, the entry stays in the list, greyed, and does not play;
- a bin: removes the entry at once, without asking.

**Add bell** (written **Add first bell** while the schedule is empty) opens the time picker.

At the bottom: **Tip: leave the phone plugged in. Each bell entry plays three singing-bowl strikes, or one if you set it to (×3 / ×1 beside its time); scheduled talks play your chosen recording.**, then **Pierre Gallaz · developed with Claude Code**.

### Pick a time

This panel opens when you add a bell, tap a time in the schedule, or schedule a talk. It is titled **Pick a time**.

- It opens ready for typing: two fields, hours and minutes, on 24 hours. Any minute can be typed. For a new entry the fields start at the current time.
- **Dial** switches to a clock face; **Type** switches back to the fields.
- For a bell, the section **This bell rings** offers **Three bells** and **One bell**, each with a play button to hear it with the chosen sound at the current bell level. A new bell starts on **Three bells**. This section is absent for a talk.
- **Set** saves. **Cancel**, or a tap outside the panel, closes it without changing anything.

### Library tab

The Library holds the talks. At the top: **Add dharma talks from your phone, a kDrive share link or a podcast feed, play them, or schedule one to play at a set time — exactly like the bells.**

Three buttons:

- **Add from this phone (MP3)** opens the phone's file picker. Despite the label, any audio file the phone can play is accepted.
- **Download from kDrive link** opens the kDrive panel.
- **Download from podcast feed** opens the podcast panel.

Below, **No talks yet.** or one card per talk, with its title (the file's name without its ending, or the episode's title) and:

- **Play**: plays the talk now; the player bar appears;
- **Schedule**: opens **Pick a time**, then adds the talk to the schedule at that time, every day, and shows the Schedule tab;
- a bin: removes the talk from the Library at once, without asking, together with every schedule entry that plays it.

### Download from kDrive

A panel titled **Download from kDrive**.

1. The field **Public share link** takes the address of a public kDrive share; the example shown is **https://kdrive.infomaniak.com/app/share/…**. The last link you used is already filled in.
2. **Connect** (it reads **Connecting…** while working) lists the audio files of the shared folder, most recently changed first. The result line reads **3 audio file(s) found.** or **No audio files found in that share.**
3. Each file shows its name and size, and a download button. Tap it: a turning circle replaces the button while the file is waiting or downloading, then **✓** when the talk is in the Library. A file whose name matches a talk already in the Library shows **✓** from the start.
4. **Done** closes the panel. Downloads go on without it.

After you tap a download button the result line reads **Downloading in the background — it lands in your Library when done. You can close this.**

### Download from podcast feed

A panel titled **Download from podcast feed**, built the same way.

1. The field **Feed URL** takes the address of a podcast feed; the example shown is **https://…/feeds/teacher.xml**. The last address you used is already filled in.
2. **Fetch episodes** (it reads **Fetching…** while working) lists the episodes in the order of the feed. The result line reads **12 episode(s) found.** or **No episodes found in that feed.**
3. Each episode shows its title and, when the feed gives them, its length (**1h 05m** or **39m 55s**) and its size, and a download button that behaves as in the kDrive panel.
4. **Done** closes the panel.

### The player bar

A dark bar at the bottom of both tabs while a talk plays, and also while a scheduled bell rings. It shows:

- the title of the talk (or **Retreat Timer** for a bell);
- a progress bar you can drag to any point of the recording;
- **0:42 elapsed** on the left and **−38:10 left** on the right (hours appear past one hour); **Playing…** if the length is not known;
- five buttons: back to the beginning, back 10 seconds, pause or play, forward 10 seconds, stop.

Stop ends playback and the bar goes away. The bar also goes away when the recording ends.

The previews (**Preview**, **Test bell**, the play button of a bell in the schedule, the play buttons in **Pick a time**) do not use the player bar. A preview stops when it ends, when you start another preview, or when the app is closed.

### The notifications

The app has three kinds of notification, each in its own category in the phone's settings.

**Bell ringing** (described as **Plays the bells at scheduled times.**). Shown while a bell rings or a talk plays; it makes no sound and no vibration of its own. Its title is **Retreat Timer** for a bell or the talk's title. Its text is first **Ringing the three bells…**, **Ringing the bell…** or **Playing dharma talk…**, then the position, for example **0:42 / 38:52 · 38:10 left**, with a progress bar. Four buttons: **−10s**, **Pause** or **Play**, **+10s**, **Stop**. Tapping the notification opens the app.

**Keep speaker awake** (described as **A silent keep-alive signal so a Bluetooth speaker won't sleep between bells.**). Shown for as long as the keep-alive runs: **Keeping the speaker awake**, **Holding the Bluetooth link open with a silent signal.**, with a **Stop** button.

**Downloads** (described as **Downloads dharma talks in the background so a transfer survives the screen locking.**). Shown while talks download: the talk's title and **Downloading talk…**, followed by **(2/3)** when several are queued.

## How to

### Make the phone ready to be left alone

1. On the **Schedule** tab, tap **Allow background running** in the amber card and accept the phone's request.
2. If the card also shows **Allow notifications**, tap it and allow notifications for the app.
3. Wait for the card to turn green: **✓ Ready — bells and talks will play on time**.
4. Leave the phone plugged in.

### Add a bell

1. On the **Schedule** tab, tap **Add bell** (or **Add first bell**).
2. Type the hour and the minutes, on 24 hours.
3. Under **This bell rings**, choose **Three bells** or **One bell**.
4. Tap **Set**.

The bell is on straight away and rings every day at that time.

### Change a bell's time, or switch it between three bells and one

1. Tap the time on the bell's card.
2. Change the time, or the choice under **This bell rings**, or both.
3. Tap **Set**.

### Switch a bell off without removing it

Turn off the switch on its card. The time turns grey and the bell no longer rings. Turn the switch on again to bring it back.

### Remove a bell or a scheduled talk

Tap the bin on its card. It is removed at once. Removing a scheduled talk leaves the talk itself in the Library.

### Hear a bell before the day

Tap the play button on the bell's card: it rings as it will at its time, three strikes or one, with the chosen sound and at the **Bells** level.

### Choose the bell sound

1. In the **Bell sound** card, tap **Preview** on a bowl to hear it.
2. Tap the selector to the left of the one you want.

The choice applies to every bell of the schedule. The five bowls are recorded at matched loudness, so changing bowl does not change the volume in the room.

### Use your own sound as the bell

1. In the **Bell sound** card, tap **Choose file** on the line **Your own sound**.
2. Pick an mp3 or wav file in the phone's file picker.
3. The app keeps its own copy, plays it once, and selects it.

A bell set to one bell plays the file once; a bell set to three plays it three times in a row. To go back to a bowl, tap that bowl's selector; to return to your file, tap its selector. To replace it, tap **Change**; the new file takes the place of the old one.

### Set the volume

1. Set the phone's alarm volume (and the speaker's own volume, with a Bluetooth speaker) to the loudest you will need. Bells and talks are played as alarms, so it is the alarm volume that counts, not the media volume.
2. In **Bells**, tap **Test bell** and drag the slider until the level is right for the room.
3. In **Talks**, tap **Test talk** and drag the slider while the talk plays. If the talk opens with a silence, drag the progress bar of the player bar to reach the speech.
4. Tap stop in the player bar.

### Add a talk that is on the phone

1. Open the **Library** tab and tap **Add from this phone (MP3)**.
2. Pick the audio file.

The talk appears in the list under the file's name. The file stays where it is on the phone; do not move or delete it afterwards.

### Download talks from a kDrive link

1. In the **Library** tab, tap **Download from kDrive link**.
2. Paste the public share link and tap **Connect**.
3. Tap the download button of each talk you want.
4. Tap **Done**. Each talk appears in the Library when its download ends.

### Download talks from a podcast

1. In the **Library** tab, tap **Download from podcast feed**.
2. Paste the feed's address and tap **Fetch episodes**.
3. Tap the download button of each episode you want.
4. Tap **Done**.

Downloads run one after the other and continue with the panel closed, the app closed or the screen locked.

### Play a talk now

In the **Library** tab, tap **Play** on the talk. Use the player bar, or the notification, to pause, move by 10 seconds, go back to the beginning or stop.

### Schedule a talk

1. In the **Library** tab, tap **Schedule** on the talk.
2. Type the time and tap **Set**.

The app shows the **Schedule** tab with the talk in the list. It plays every day at that time until you switch it off or remove it. To change its time, tap the time on its card.

### Remove a talk from the Library

Tap the bin on the talk's card. The talk and all its entries in the schedule are removed at once.

### Ring through a Bluetooth speaker

1. Connect the speaker to the phone in the phone's Bluetooth settings.
2. In the app, check that the **Keep Bluetooth speaker awake** card reads **✓ A Bluetooth speaker is connected**.
3. Turn the switch on, so the speaker does not disconnect during the silences.
4. Set the levels with **Test bell** and **Test talk**.
5. Keep the phone and the speaker plugged in.

When a Bluetooth speaker is connected, the app sends bells and talks to it rather than to the phone's own speaker.

### Stop a bell or a talk that is playing

Tap stop in the player bar, or **Stop** in the notification.

## Settings

All settings are on the **Schedule** tab; there is no separate settings screen.

| Setting | What it changes | Choices | Default |
|---|---|---|---|
| **Bell sound** | The sound of every bell | **Singing bell**, **Tibetan bowl (E♭)**, **Gong bowl**, **Satipanya**, **enpleineconscience.ch**, or your own file | **Singing bell** |
| **Your own sound** | A file from the phone used as the bell | one mp3 or wav file | none |
| **Bells** (under **Levels**) | How far the bells are turned down from the phone's volume | 5% to 100% | 100% |
| **Talks** (under **Levels**) | How far the talks are turned down from the phone's volume | 5% to 100% | 100% |
| **Keep Bluetooth speaker awake** | Sends a silent signal between bells so a wireless speaker stays connected | on, off | off |
| **This bell rings** (in **Pick a time**, per bell) | How many strikes this bell rings | **Three bells**, **One bell** | **Three bells** |
| Switch on each schedule card | Whether this entry plays | on, off | on |

The two readiness steps belong to the phone, not to the app: the exemption from battery optimisation and the permission to show notifications. Both are missing on a fresh install.

The app also remembers the last kDrive link and the last podcast address you used.

## Your data

Everything stays on the phone: the schedule, the settings, the list of talks, the copy of your own bell sound and the talks you downloaded. There is no account, no sync and no tracking.

The network is used only when you ask for talks:

- **Connect** and the kDrive downloads contact Infomaniak's kDrive service, with the public link you pasted;
- **Fetch episodes** contacts the address of the feed, and each episode is downloaded from the address the feed gives for it.

Nothing else is sent, to anyone.

Talks are kept in two ways. A talk added with **Add from this phone (MP3)** is not copied: the app remembers where the file is and reads it there, so the file must stay in place. A talk downloaded from kDrive or from a podcast is saved inside the app. Your own bell sound is copied into the app when you choose it; the original file can be moved or deleted afterwards.

Removing a downloaded talk from the Library takes it out of the list and out of the schedule; the app does not erase the downloaded file itself, which keeps its place in the app's storage until you clear the app's data or uninstall it.

The schedule is set again by itself after the phone restarts, after a change of time or time zone, and after an update of the app. If the keep-alive switch is on, the silent signal starts again at the same moments.

There is no export and no import. The app does not exclude itself from Android's device backup; if you have turned that on in the phone, Android may include the app's data in it.

Uninstalling the app erases the schedule, the settings, the downloaded talks and the copy of your bell sound. Files you added from the phone are not touched.

## With the other apps

Retreat Timer has no home-screen widget and no tile in Reader's Launcher, and it does not receive content shared from other apps.

It reads audio files through the phone's file picker (for talks and for your own bell sound), public share links from kDrive, and podcast feeds.

## Limits

- The schedule repeats every day. You cannot choose days of the week or dates.
- There is no countdown and no timed sitting: only times of day.
- One bell sound serves the whole schedule. Only the number of strikes, three or one, is set per bell. One sound of your own is kept at a time.
- A bell or talk that could not play at its time because the phone was off is skipped, not played late.
- Only one thing plays at a time. A bell or a talk that starts while another is playing cuts it off; a bell placed in the middle of a scheduled talk ends the talk.
- The levels cannot go under 5%, so that a slip of the finger never silences a bell.
- The kDrive panel lists the audio files at the top of the shared folder only (mp3, m4a, aac, wav, ogg, flac, opus, mp4), not those in sub-folders, and only for a public share.
- The podcast panel lists only episodes that carry an audio file. Episodes are downloaded, never streamed.
- A download shows no percentage. A failed download is discarded whole and starts over from the beginning.
- A talk cannot be renamed, and the Library cannot be reordered.
- The app is in English only, in light colours only, and in portrait only.

## Messages and problems

| What you see | What it means, what to do |
|---|---|
| **⚠ One step left for guaranteed playback** | The app is not exempt from battery optimisation, or notifications are not allowed. Tap the button or buttons in the card. |
| **✓ Ready — bells and talks will play on time** | Nothing to do. Keep the phone charged. |
| **Nothing scheduled yet — add a bell below or schedule a talk.** | The schedule is empty, or every entry is switched off. |
| **No Bluetooth speaker connected right now** | The phone sees no wireless speaker. Bells will come from the phone itself. Reconnect the speaker in the phone's Bluetooth settings. |
| **No talks yet.** | The Library is empty. Use one of the three buttons above. |
| **Trims talks independently of the bells. Add a talk in the Library tab to test it.** | **Test talk** is greyed because the app has no talk to play. |
| **Could not connect: Not a kDrive share link** | The address is not a kDrive share link. It must contain **/app/share/** followed by a number and the link's code. |
| **Could not connect: This share is not public (…)** | The share is protected. Ask its owner for a public link. |
| **Could not connect: …** with another text | The kDrive service could not be reached or refused the request. Check the connection and the link, then tap **Connect** again. |
| **No audio files found in that share.** | The shared folder holds no audio file at its top level. |
| **Could not read the feed: …** | The address could not be reached, or what it returns is not a podcast feed. Check the address and tap **Fetch episodes** again. |
| **No episodes found in that feed.** | The feed has no episode with an audio file. |
| **Downloading in the background — it lands in your Library when done. You can close this.** | The download is under way; you can tap **Done**. |
| **Failed: … — tap to retry** under a file or an episode | The download failed and nothing was kept. Tap the download button on that line to try again. |
| **Playing…** in the player bar | The length of the recording is not known; the progress bar is not shown. |

**The green card does not appear after you allowed everything.** The card checks about every half minute. Wait a moment.

**Nothing happens after choosing your own sound.** The phone could not read the file as a sound, so the app kept what it had. Choose another file, mp3 or wav.

**A talk added from the phone no longer plays.** The file was moved, renamed or deleted. Remove the talk from the Library and add it again from where it is.

**A scheduled talk stops before its end.** Another entry of the schedule started while it was playing. Leave enough time after a talk before the next bell.

**The bell comes from the phone instead of the speaker.** The speaker disconnected. Reconnect it, then turn on **Keep Bluetooth speaker awake**.

**You tapped Stop in the notification Keeping the speaker awake and the switch in the app is still on.** The silent signal is stopped all the same. To start it again, turn the switch off and on.

**The bell is too quiet even at 100%.** The levels only turn the sound down. Raise the phone's alarm volume, and the speaker's own volume.

**The bell rings while the phone is on silent.** That is intended: bells and talks are played as alarms. To have silence, turn off the switches in the schedule.

**An alarm icon shows in the phone's status bar.** Each entry of the schedule is set as an alarm-clock alarm, the kind the phone fires at the exact time, so the phone shows its usual alarm sign.


# Retreat Player

*Android 1.5.1*

## What it is

Retreat Player plays the recordings of a meditation retreat: talks, bells, guided meditations and chanting. You load recordings from the phone's files, from a shared kDrive folder or from a podcast feed; each one is copied into the app, so playing needs no network and airplane mode is fine. Its one principle is that once a recording has started, nothing interrupts it: it keeps playing with the screen off, it does not pause or lower itself for another app's sound, and when it ends nothing else starts. It is not a music player: there are no playlists, no automatic next recording, no shuffle, no playback speed, no sleep timer, no account and no advertising.

The app is in English only, whatever the phone's language. It works in portrait only and needs Android 8.0 or later.

## First start

On Android 13 and later, the app asks once for permission to show notifications. It uses two notifications: one while a recording plays (with pause, stop and 10-second buttons) and one while recordings download. The app does not insist: it carries on whether you accept or refuse.

The app asks for no other permission. To load files from the phone it opens the phone's own file chooser, and it only receives the files you pick there.

There is no account and nothing to fill in. The first screen shows:

- the title **Retreat Player** and the line **Talks and chanting, stored on this phone, uninterrupted.**;
- a round **+** button at the top right;
- three sections, **Bells & chanting**, **Guided meditations** and **Dharma talks**, each with the line **Nothing here yet — load recordings with the + button.**;
- a dark band at the bottom with **Nothing playing — tap ▶ on a recording**.

Tap **+** to load your first recordings.

## The screens

The app has one screen (the home page), with the player as a band at its bottom, and one panel for loading recordings.

### Home

At the top are the app's name, its subtitle and the round **+** button, which opens the **Load recordings** panel.

Below, the recordings are listed in sections, always in this order:

1. **Bells & chanting**
2. **Guided meditations**
3. **Dharma talks**
4. **Just loaded — move into a category**

The first three sections are always there; an empty one shows **Nothing here yet — load recordings with the + button.** The fourth, written in brown, appears only while it holds something: every recording you load arrives there, at the bottom of the page, and waits to be filed.

Each recording is a white tile. From left to right it carries:

| Control | What it does |
|---|---|
| **▶** | Plays this recording from its beginning. If another recording was playing, it is replaced. On the tile of the recording that is in the player, the button shows the pause sign while it plays and pauses or resumes it. |
| Title and length | The title (two lines at most) and, in brown, the length: **< 1 min**, **58 min**, **1 h 02**. The length is missing when the app could not read it. Tapping the title does nothing; only **▶** starts playback. |
| **▲** | Moves the tile one place up within its section. Greyed out on the first tile of a section. |
| **▼** | Moves the tile one place down within its section. Greyed out on the last tile of a section. |
| **⋮** | Opens the tile's menu. |

The tile of the recording that is in the player is outlined in brown.

The **⋮** menu holds:

| Entry | What it does |
|---|---|
| **Move to Bells & chanting** | Files the recording at the bottom of that section. |
| **Move to Guided meditations** | Files the recording at the bottom of that section. |
| **Move to Dharma talks** | Files the recording at the bottom of that section. |
| **Delete** (in red) | Removes the recording from the app at once, without asking for confirmation. If it was playing, playback stops. |

The menu lists only the sections the recording is not in. No entry sends a recording back to **Just loaded — move into a category**. Tap outside the menu to close it without choosing.

At the very bottom of the list is the line **Pierre Gallaz · developed with Claude Code**.

### The player

The dark band at the bottom of the home page is always visible.

When nothing is in the player it reads **Nothing playing — tap ▶ on a recording**.

When a recording is in the player, playing or paused, the band shows:

- the title of the recording (two lines at most);
- a progress bar with a round handle: drag the handle either way to move through the recording. The two times follow your finger while you drag, and the recording jumps to that place when you lift it;
- on the left, the time played so far, in large figures, with **elapsed** beneath;
- in the middle, the total length, as **of 58:12**;
- on the right, the time left, preceded by a minus sign, with **remaining** beneath.

Times are written minutes:seconds, or hours:minutes:seconds from one hour up. The progress bar and the total length are missing when the app cannot tell how long the recording is.

Under the times are five buttons, from left to right:

| Button | What it does |
|---|---|
| Back to beginning (a bar and a triangle pointing left) | Returns to 0:00. If the recording was playing it goes on playing from the start; if it was paused it stays paused. |
| Back 10 seconds (an arrow circling back, marked 10) | Goes back 10 seconds, or to the beginning if fewer than 10 seconds have played. |
| Play / Pause (large brown disc) | Pauses, or resumes where you paused. |
| Forward 10 seconds (an arrow circling forward, marked 10) | Skips 10 seconds ahead, or to the end if fewer than 10 seconds remain. |
| Stop (a square) | Ends playback and empties the player. The place you had reached is not kept. |

When the recording reaches its end, the player empties itself and the band returns to **Nothing playing — tap ▶ on a recording**. Nothing else starts.

As long as a recording is in the player, playing or paused, and the app is on screen, the screen does not switch off by itself. It behaves normally again as soon as you press Stop or the recording ends.

### Load recordings

Tapping **+** opens a panel titled **Load recordings** with three buttons:

| Button | What it does |
|---|---|
| **Files on this phone** | Opens the phone's file chooser at once. |
| **Shared kDrive folder (public link)** | Shows a field for the link of a shared folder. |
| **Podcast feed** | Shows a field for the address of a feed. |

**Done**, at the bottom right, closes the panel. You can also close it by tapping outside it or with the phone's back button, except while it is connecting or copying. The panel has no way back to the three buttons: to change source, tap **Done** and then **+** again.

**From this phone.** The phone's file chooser lets you pick one or several files. Back in the panel, now titled **From this phone**, the picked files are listed, all ticked, under **3 file(s) picked — press Load.** (or **Nothing picked.** if you left the chooser without picking). The title of each recording is the name of the file without its ending.

**From shared kDrive folder.** The panel shows the field **Public share link — no password needed**, with the example **https://kdrive.infomaniak.com/app/share/…**, and the button **Connect**, which reads **Connecting…** while the app contacts kDrive. The app then lists the audio files found in the folder, most recently modified first, under **12 audio file(s) found — tick the ones to load.** None is ticked. Only the files directly in the shared folder are listed, not those in its sub-folders, and only files whose name ends in mp3, m4a, aac, wav, ogg, flac, opus or mp4.

**From podcast feed.** The panel shows the field **Feed URL**, with the example **https://…/feeds/teacher.xml**, and the button **Fetch episodes**, which reads **Fetching…** while the app reads the feed. The episodes are then listed under **40 episode(s) found — tick the ones to load.** None is ticked. Only episodes that have a title and an audio file appear.

**The list.** Each line has a tick box, the title and, in small grey print, the length (when the feed gives it) and the size in KB or MB (when known). At the left of a line you see one of three things:

- a tick box, for a recording you can choose;
- a small turning circle that fills up, for a recording being downloaded;
- a green **✓**, for a recording whose title is already in the app.

Under the list is the button **Load**, which becomes **Load 3 recording(s)** once you have ticked some.

What happens when you press it depends on the source:

- Files from the phone are copied straight away. The panel shows **Copying 1/3 — title** with a bar, and cannot be closed until the copy ends. It then reads **Loaded 3 recording(s) — stored on this phone, available offline.**
- kDrive files and podcast episodes are downloaded in the background, one after the other. The panel reads **Downloading 3 in the background — they appear on your homepage as they finish. You can close this.** You can close the panel, leave the app or let the screen go dark: the downloads go on.

A download that fails shows **Failed: … — tick to retry** on its line, in brown, and gets its tick box back.

### The notifications

**While a recording is in the player**, a notification shows its title, a progress bar and a line such as **12:40 elapsed  ·  45:32 left** (or **Playing…** when the length is not known). It carries four buttons: **Back 10 seconds**, **Pause** (or **Play** when paused), **Forward 10 seconds** and **Stop**. They do exactly what the same buttons do in the app. Tapping the notification itself opens the app. The notification goes away when the recording ends or when you press Stop.

**While recordings download**, another notification shows the title of the recording being fetched, a bar, and **Downloading (42%)**, followed by **·  2/5** when several are queued. Tapping it opens the app. It goes away when the last download ends.

In the phone's notification settings for the app, the two kinds are named **Playback** (**Shows what is playing and its transport controls.**) and **Downloads** (**Downloads recordings in the background.**). Both are silent.

## How to

### Load recordings from the phone's files

1. Tap **+**.
2. Tap **Files on this phone**.
3. In the phone's file chooser, pick one or several files and confirm.
4. Back in the panel, untick any file you do not want.
5. Tap **Load 3 recording(s)**.
6. Wait for **Loaded 3 recording(s) — stored on this phone, available offline.**, then tap **Done**.

The recordings are now under **Just loaded — move into a category** at the bottom of the home page. The app has made its own copy: you may delete or move the original files.

The chooser also offers files that are not audio, because some audio files (FLAC and Opus especially) are not labelled as audio by the phone. Pick only recordings.

### Load recordings from a shared kDrive folder

The folder must be shared from Infomaniak kDrive with a public link, without a password.

1. Tap **+**.
2. Tap **Shared kDrive folder (public link)**.
3. Paste the link in **Public share link — no password needed**. It looks like **https://kdrive.infomaniak.com/app/share/…**
4. Tap **Connect**.
5. Tick the recordings you want.
6. Tap **Load 3 recording(s)**.
7. Tap **Done** if you wish; the downloads continue and each recording appears on the home page as it arrives.

The link is remembered once a connection has succeeded: next time the field is already filled and you only tap **Connect**.

### Load episodes from a podcast feed

1. Tap **+**.
2. Tap **Podcast feed**.
3. Type or paste the address of the feed in **Feed URL**.
4. Tap **Fetch episodes**.
5. Tick the episodes you want.
6. Tap **Load 3 recording(s)**.
7. Tap **Done** if you wish; the downloads continue in the background.

The address is remembered once the feed has been read: next time the field is already filled. The app remembers one kDrive link and one feed address, the last ones that worked.

### Follow a download

Pull down the phone's notifications: the **Downloads** notification gives the recording being fetched, its percentage and its place in the queue.

In the app, the recording appears under **Just loaded — move into a category** as soon as it is complete. If you kept the panel open, the line shows a circle that fills up, then a green **✓**.

### Retry a download that failed

1. In the panel, find the line marked **Failed: … — tick to retry**.
2. Tick it.
3. Tap **Load 1 recording(s)**.

If you had closed the panel, open it again with **+**, choose the same source and tap **Connect** or **Fetch episodes** to get the list back. A download that fails leaves nothing behind; it starts again from zero.

### File a recording in a section

1. On the recording's tile, tap **⋮**.
2. Tap **Move to Bells & chanting**, **Move to Guided meditations** or **Move to Dharma talks**.

The recording goes to the bottom of that section. The same menu moves it later from one section to another.

### Change the order of the recordings

Tap **▲** or **▼** on a tile to move it one place up or down. A tile moves only within its own section. The order is kept.

### Play a recording

Tap **▶** at the left of its tile. It starts from the beginning, its tile gets a brown outline, and the player at the bottom shows its progress.

When playback starts, the app asks the phone for the sound, so that other players that respect this pause. From then on the app ignores every such request made by another app: it neither pauses nor lowers its volume.

The loudness is the phone's media volume.

### Pause and resume

Tap the large brown disc in the player, or the button at the left of the tile, or **Pause** in the notification. Tap again to resume at the same place.

### Go to a passage

- Drag the handle of the progress bar and lift your finger where you want to be; the **elapsed** and **remaining** times tell you where you are while you drag.
- For a small step, tap the back-10-seconds or forward-10-seconds button.
- To hear the recording again from the start, tap the back-to-beginning button.

### Stop

Tap the square in the player, or **Stop** in the notification. The player empties; playing the recording again starts it from the beginning.

### Listen with the screen off or from another app

Press the phone's power button, or leave the app: playback continues. Use the notification to pause, move by 10 seconds or stop without opening the app.

### Use the app without network

Load everything you need while you have a connection and wait until every recording has arrived on the home page. After that you can switch the phone to airplane mode: playing, filing, ordering and deleting need no network.

### Delete a recording

1. On its tile, tap **⋮**.
2. Tap **Delete**.

The recording disappears at once; there is no confirmation and no way to undo. Only the app's copy is removed: the original file on the phone, in the kDrive folder or in the podcast is untouched, and you can load it again.

## Settings

The app has no settings screen and no option to set. Its only choices are the order and the section of each recording, and the link and feed address it remembers for you.

The notifications can be turned off, separately for **Playback** and **Downloads**, in the phone's own settings for the app.

## Your data

Everything lives on the phone, inside the app's private storage, which other apps cannot read:

- a copy of every recording you loaded;
- the list of recordings, with each one's title, length, section and place;
- the last kDrive share link and the last podcast feed address that worked.

The app has no account, no sync and no server of its own. It contains no advertising and no tracking.

The network is used only when you load from kDrive or from a podcast:

- **Connect** and the downloads that follow contact kdrive.infomaniak.com, with the share link you gave;
- **Fetch episodes** contacts the server of the feed address, and the downloads contact the servers where the episodes are hosted, following redirections.

Feeds and episodes served over plain http (not https) are accepted. Loading files from the phone and playing recordings use no network at all.

There is no export, no import and no backup function in the app. The app does not opt out of Android's own backup of app data; whether your phone uses it depends on the phone's backup settings.

Uninstalling the app, or clearing its data in the phone's settings, removes every loaded recording, the list and the remembered addresses. The original files, the kDrive folder and the podcast are not affected.

## With the other apps

Retreat Player stands alone. It offers no home-screen widget, does not appear in the "share" or "open with" menus of other apps, and exchanges nothing with the other apps of the family. The only way to bring a recording in is the **+** button.

Its sibling is Retreat Timer, a meditation timer; the two apps are independent of each other.

## Limits

- One recording at a time, played once. No queue, no playlist, no automatic next recording, no repeat.
- The place you reached in a recording is not remembered: after Stop, after the end, or if the app is closed by the phone, the recording starts again from the beginning. Pause keeps the place only as long as the recording stays in the player.
- No playback speed, no sleep timer, no bookmarks, no equaliser.
- A recording cannot be renamed. Its title is the file's name, or the episode's title in the feed.
- No search. Three fixed sections; you cannot add, rename or remove a section.
- A tile moves one place at a time, with the arrows; there is no dragging.
- Deleting is immediate, one recording at a time.
- kDrive: public links without a password only; only the files directly in the shared folder; only names ending in mp3, m4a, aac, wav, ogg, flac, opus or mp4.
- Podcast: the app does not subscribe to a feed and does not check for new episodes; you fetch the list each time you want to load something. Feeds that require a login are not supported.
- Whether a file plays depends on the audio formats the phone itself can play.
- Downloads run one at a time. A download that is cut is not resumed; it starts again from zero when you retry. If the app is closed by the phone while downloads are waiting, those that had not finished are dropped and must be chosen again.
- In the list, the green **✓** is given by title: a file or episode with the same title as a recording already in the app is shown as already loaded and cannot be ticked. Files picked on the phone are the exception: they arrive ticked, and pressing **Load** copies them again even when they show a **✓**, which gives two tiles with the same title.
- Portrait only. English only. No dark theme.

## Messages and problems

| Message | What it means, what to do |
|---|---|
| **Nothing here yet — load recordings with the + button.** | This section is empty. Load recordings with **+**, then file them here with **⋮**. |
| **Nothing playing — tap ▶ on a recording** | The player is empty. |
| **Nothing picked.** | You left the phone's file chooser without picking a file. Tap **Done**, then **+** and **Files on this phone** again. |
| **3 file(s) picked — press Load.** | The files are chosen but not yet copied. Tap **Load 3 recording(s)**. |
| **Copying 1/3 — title** | A file from the phone is being copied into the app. Wait. |
| **Loaded 3 recording(s) — stored on this phone, available offline.** | The copy is done. The recordings are at the bottom of the home page. |
| **“title” failed: …** | A file from the phone could not be copied; the end of the message is the reason given by the phone. Pick the file again; check that it is still there and that the phone has free space. |
| **Could not connect: Not a kDrive share link** | The link does not have the form of a kDrive share link. Copy the whole link again from kDrive; it contains **/app/share/** followed by a number and a code. |
| **Could not connect: This share is not public (right=…)** | The folder is shared with a password or with restricted access. Ask for a public link without a password. |
| **Could not connect: …** (anything else) | kDrive could not be reached or answered with an error (shown as **HTTP** followed by a number). Check the connection and the link, then tap **Connect** again. |
| **No audio files in that share.** | The shared folder holds no audio file at its top level. Recordings in sub-folders are not seen: ask for a link to the folder that holds the files themselves. |
| **12 audio file(s) found — tick the ones to load.** | The folder was read. Tick, then tap **Load**. |
| **Could not read the feed: …** | The address could not be reached or is not a podcast feed. Check the address and the connection, then tap **Fetch episodes** again. |
| **No episodes in that feed.** | The feed was read but holds no episode with an audio file. |
| **40 episode(s) found — tick the ones to load.** | The feed was read. Tick, then tap **Load**. |
| **Downloading 3 in the background — they appear on your homepage as they finish. You can close this.** | The downloads are queued. You can tap **Done**. |
| **Failed: … — tick to retry** | This download did not complete: the reason is given (for example **HTTP** followed by a number, **Too many redirects**, **Download failed**, or a network message from the phone). Tick the line and tap **Load** again. |
| **Playing…** (in the notification) | A recording is playing and its length is not known. |

**The Load button is grey.** Nothing is ticked, or the panel is busy connecting or copying.

**A line shows a green ✓ and no tick box.** A recording with that title is already in the app.

**You tap ▶ and nothing happens, the player stays empty.** The file is not audio the phone can play. Delete the tile and load the recording in another format, MP3 for example.

**A tile shows no length.** The app could not read the length of the file. If it plays, it plays normally.

**A downloaded recording has not appeared.** Check the **Downloads** notification: downloads arrive one at a time. If the notification is gone and the recording is missing, the download failed; load it again.

**The screen stays on.** This is intended while a recording is in the player, even paused, so that the progress stays readable. Press Stop to let the screen switch off by itself, or switch it off with the power button: playback continues.

**Music from another app stopped when a recording started.** This is intended: the app takes the sound when it starts playing.

**You cannot find how to go back to the three source buttons.** Tap **Done**, then **+**.


# Retreat Walk

*Android 1.1.0*

## What it is

Retreat Walk rings a singing bowl at a fixed interval, every 10 minutes for example, again and again until you stop it. It is meant for switching partners in a paired exercise, for walking meditation, or as a regular reminder to stay awake while sitting. The whole app is one number and one button: the minutes between bells, and **Start**. Each bell is counted from the moment you pressed **Start**, not from the bell before, so the bells stay on the clock even after hours, with the screen locked and the phone asleep.

It deliberately does nothing else: no end time, no choice of sound, no statistics, no account. It cannot use the network at all.

The app is in English only, whatever the language of the phone. It runs on Android 8.0 and later.

## First start

There is no account, no server and nothing to fill in. The app opens on its single screen, with **10** already in the field **Minutes between bells**, and it is ready to use.

The app asks one permission, and only on Android 13 and later: the permission to show notifications. It asks the first time you press **Start**, not when the app opens. The notification it is for is the silent one that stays visible during a session and carries the **Stop** button, which lets you end a session from the lock screen.

- The session starts as soon as you press **Start**, while the question is still on screen.
- If you refuse, the session runs and rings all the same; you then stop it from the app only. The app asks again the next time you press **Start**.

## The screens

The app has a single screen, always upright (it does not turn with the phone), dark text on a paper-coloured background. There is no menu and no settings screen.

### The main screen, before a session

From top to bottom:

- The title **Retreat Walk** and the line **A bell every so many minutes, until you stop it.**
- The field **Minutes between bells**, followed by **min**. Tap it to type a number. It accepts digits only, three at most.
- Under the field, the line **The bell rings at that many minutes, then twice that, then three times — on and on.** If the number is outside the allowed range, this line turns red and reads **Choose between 1 and 180 minutes.**
- The large **Start** button. It is greyed out while the field is empty or the number is not between 1 and 180.
- If the phone's alarm volume is below 85 %, a red line **Alarm volume is at 40% — the bell can be no louder than that.** (with the real percentage) and, under it, **Open sound settings**, which opens the phone's sound settings. Both disappear by themselves, within a couple of seconds, once the alarm volume is at 85 % or more.
- The line **For switching partners in a paired exercise, or a regular reminder to stay awake while sitting.**
- At the very bottom, **Pierre Gallaz · developed with Claude Code**.

### The main screen, during a session

The **Start** button becomes a red **Stop** button, and the minutes field is greyed out: the interval cannot be changed while a session runs.

Under the button (and under the volume warning, if it is shown) you see:

- **Next bell in** and a large countdown, in minutes and seconds (**07:42**), or in hours, minutes and seconds when more than an hour remains (**1:02:30**).
- The number of bells so far: **No bell yet — every 10 min from the start** before the first one, then **1 bell so far**, **2 bells so far**, and so on.
- The reminder **You can lock the screen. Stop is in the notification too.**

### The notification

During a session, a silent notification stays in place. It makes no sound and no vibration: the bowl is the only sound the app makes.

- Its title is **Bell every 10 min** (with your interval).
- Before the first bell, its text is **First bell at 14:30 — tap Stop to end**. After that it reads **3 rung · next at 15:00 — tap Stop to end**. Times are always shown on the 24-hour clock.
- Its **Stop** button ends the session, also from the lock screen.
- Tapping the notification itself opens the app.

The notification disappears when the session ends.

## How to

### Start a bell every so many minutes

1. Open Retreat Walk.
2. Tap the field **Minutes between bells** and type a whole number from 1 to 180.
3. Press **Start**.

Nothing rings at the start. The first bell rings after that many minutes, the second at twice that, the third at three times, and so on, with no end.

### Stop the bells

Press **Stop** in the app, or press **Stop** on the notification (this works from the lock screen). The session ends at once; if the bowl is sounding at that moment, it is cut short.

### Change the interval

1. Press **Stop**.
2. Type the new number of minutes.
3. Press **Start**. The count starts again from that moment.

### Lock the screen or use another app during a session

Just do it. The session continues with the screen off or with another app in front. To come back to the countdown, open the app again or tap the notification.

### See when the next bell will ring

In the app, read the countdown under **Next bell in**. Without opening the app, read the notification: it gives the clock time of the next bell.

### Make the bell louder

The bell plays on the phone's alarm volume, not on the media or ringtone volume, and at the fullest level that volume allows.

1. If the app shows **Alarm volume is at … % — the bell can be no louder than that.**, tap **Open sound settings**.
2. Raise the alarm volume.
3. Come back to the app. The warning disappears once the volume is at 85 % or more.

You can also reach the alarm volume with the phone's volume keys.

### Find the last interval again

You do not need to do anything: the field opens with the interval of the last session you started.

## Settings

The app has no settings screen. The only thing you set is the interval.

| Setting | Choices | Default |
|---|---|---|
| **Minutes between bells** | a whole number from 1 to 180 | 10, then the interval of your last session |

Two things are set in the phone, not in the app:

- the alarm volume, which decides how loud the bell is;
- the notification category of the app, named **Bell session** (**Shows the running session and its Stop button.**), which you find in the phone's notification settings for Retreat Walk.

## Your data

Everything stays on the phone. The app keeps only the interval you last used and, during a session, when it started, its interval and how many bells have rung. It has no account, no ads and no tracking, and it has no permission to use the network: it sends nothing to anyone.

There is nothing to export, import or synchronise. If the phone's own backup is turned on, Android may include the app's saved interval in it. Uninstalling the app removes everything it stored.

## With the other apps

Retreat Walk offers no home-screen widget, receives nothing shared from other apps and opens no files.

The bell is one strike of the Satipanya singing bowl, from the same recording as the bell of Retreat Timer.

While the bowl sounds, the app asks the phone for priority on sound: music, a podcast or any other audio is lowered or paused by its own app for those few seconds, then resumes. The bell rings whether or not the other app steps aside.

## Limits

- The interval is a whole number of minutes, from 1 to 180. No seconds, no fractions.
- There is no bell at the start, and no end time: the bells continue until you press **Stop**.
- One session at a time, with a single interval.
- The sound cannot be changed: it is always one strike of the same bowl, about fifteen seconds long.
- There is no pause. Stopping and starting again begins a new count from zero.
- A session does not survive a restart of the phone. After a restart the app shows **Start**, and no bell rings until you start a new session.
- A bell whose moment has passed while the phone could not ring it is skipped, not rung late; the following bells stay at their planned times, and the count of bells includes the skipped one.
- The app is in English only, in light colours only, upright only.

## Messages and problems

**Choose between 1 and 180 minutes.** The number typed is 0 or above 180. Type a number from 1 to 180; **Start** becomes available again.

**Start is greyed out.** The field is empty or holds a number outside 1 to 180.

**Alarm volume is at … % — the bell can be no louder than that.** The phone's alarm volume is below 85 %. The bell cannot be louder than that volume, so it may be faint or, at 0 %, silent. Tap **Open sound settings** and raise the alarm volume.

**I did not hear the bell.** Check the alarm volume first: the media and ringtone volumes have no effect on the bell. Outdoors, keep the phone's loudspeaker uncovered.

**There is no notification, and no Stop on the lock screen.** The notification permission was refused. The session still runs and rings; stop it from the app. To get the notification back, press **Start** again and accept the question, or allow notifications for Retreat Walk in the phone's settings.

**The app shows Start although a session was running.** The phone was restarted, which ends the session. Press **Start** to begin a new one.

**My music or podcast pauses or drops in volume every few minutes.** This is the bell taking priority for the few seconds it sounds. It resumes afterwards.

**The phone shows an alarm at the time of the next bell.** Each bell is set in the phone as an alarm, which is what makes it ring on time with the screen off. The phone may therefore show its alarm symbol during a session. It disappears when you press **Stop**.




<!-- Browser extensions and Linux tools -->


# PageTurn

*Chrome extension 1.0.0 · bookmarklet for other browsers and phones*

## What it is

PageTurn takes the article on the web page you are looking at and lays it out as the pages of a book: no scrolling, and pages that change at once, with no animation, which is what an e-ink screen needs. It keeps the text and the pictures of the article and leaves out the menus, side columns, advertisements, subscription boxes and comments.

It exists in two forms: an extension for Chrome, and a bookmarklet (a bookmark that runs PageTurn when you open it) for any browser, phones included.

It has no settings: the page is always white, the text black, in a serif typeface of fixed size. It does not remember where you stopped reading, and it keeps nothing about you.

The interface is in English only.

## First start

### The Chrome extension

1. Download the ZIP from gallaz.ch/apps and extract it.
2. In Chrome, open `chrome://extensions/`.
3. Turn on **Developer mode**.
4. Choose **Load unpacked** and select the extracted folder.

The extension asks for two permissions: to act on the tab you are in at the moment you call it, and to insert its reading layout into that tab. It does nothing on a page until you call it there.

### The bookmarklet

The extracted folder contains a page named `bookmarklet.html`. Open it in the browser where you want PageTurn.

- **On a computer**: drag the **PageTurn** button of that page to the bookmarks bar.
- **On an iPhone or iPad (Safari)**: tap **Share**, then **Add Bookmark** on that page; then edit the bookmark and replace its address with the text shown under **Show bookmarklet URL (for manual install)**.
- **On Android (Chrome or Brave)**: bookmark that page, edit the bookmark and replace its address with the text shown under **Show bookmarklet URL (for manual install)**. To use it, type `PageTurn` in the address bar and tap the bookmark that is suggested.

## The screens

### The extension's window

Click the PageTurn icon in Chrome's toolbar. A small window shows the name **PageTurn**, one button and the line **Shortcut: Alt+P**.

- **Start Reading Mode** turns the current tab into pages. The window closes.
- When the tab is already in pages, the button is red and reads **Stop Reading Mode**: it brings the original page back.

### The reading view

The article fills the whole window, on a white background, with margins on all sides. Text is set in a serif typeface, headings in a sans-serif one. A picture is never taller than four fifths of the window and is never cut between two pages.

- A counter shows the page you are on and the number of pages, for example **3 / 12**. It is at the bottom right with the extension, at the bottom centre with the bookmarklet.
- A round **×** button at the top right leaves the reading view. With the extension, its tip reads **Exit reading mode (Esc)**.

Keys, in both forms:

| Key | What it does |
|---|---|
| Right arrow, or Space | Next page |
| Left arrow, or Shift+Space | Previous page |
| Home | First page |
| End | Last page |
| Esc | Leave the reading view |

Touch, with the bookmarklet only:

| Gesture | What it does |
|---|---|
| Swipe to the left | Next page |
| Swipe to the right | Previous page |
| Tap in the right 30% of the screen | Next page |
| Tap in the left 30% of the screen | Previous page |
| Tap in the middle | Nothing: the middle is left free so that you can select text |

A swipe counts when the finger travels at least 50 pixels sideways in less than half a second.

## How to

### Read an article as pages

1. Open the article.
2. With the extension: click the PageTurn icon, then **Start Reading Mode**, or press **Alt+P**. With the bookmarklet: open the **PageTurn** bookmark.
3. Turn the pages with the arrow keys or Space (or by swiping or tapping, with the bookmarklet).

### Go back to the normal page

Press **Esc**, or click **×**, or call PageTurn a second time (**Alt+P**, **Stop Reading Mode**, or the bookmark again). The page comes back as it was, scrolled to where you had left it.

### Jump to the beginning or the end

Press **Home** for the first page, **End** for the last.

### Change the size of the window, or turn a tablet

Just do it: PageTurn cuts the pages again for the new size and puts you at the page that corresponds to where you were.

### Change the shortcut

**Alt+P** is the shortcut the extension proposes to Chrome. Chrome lists the shortcuts of extensions at `chrome://extensions/shortcuts`, where you can give it another one.

### Clear the ghost images of an e-ink screen while reading

On a Lenovo ThinkBook Plus running Tinta4PlusU with the e-ink screen enabled, there is nothing to do: the extension asks Tinta4PlusU for a full refresh of the screen every five page turns. The bookmarklet does not do this.

## Your data

PageTurn stores nothing: no account, no history, no reading position. It works on the page already loaded in your browser and sends nothing to the internet.

The extension makes one kind of request, to your own computer only: when the reading view starts it checks whether Tinta4PlusU is listening (address `127.0.0.1`, port 19849), and then asks it for a screen refresh every five page turns. The request carries nothing about the page. If nothing answers, the extension stops asking until the next time you start the reading view. The bookmarklet makes no request at all.

## With the other apps

- **Tinta4PlusU**: clears e-ink ghosting every five page turns, as described above (extension only).

## Limits

- No choice of typeface, size, margins or colours.
- The place where you stopped is not kept: calling PageTurn again starts at page 1.
- The extension has no touch gestures and no tap zones: swiping and tapping exist in the bookmarklet only.
- PageTurn looks for the article with what it knows of Substack, Medium, WordPress, Ghost, Blogger, Dev.to, Hashnode, Hugo and Jekyll sites, then of pages built in the usual way; failing that it takes the largest block of text on the page. On an unusual page it can pick the wrong block.
- Embedded frames are removed, so a video or another embedded item inside the article disappears. Comments, related-article lists and sharing buttons are removed too.
- Anything the site marks with a name containing "ad-" or "promo" is removed as advertising; a legitimate part of an article can be removed by mistake.
- The pages are made from the page as it is when you call PageTurn: what a site loads later is not included.
- It cannot run on the browser's own pages (such as `chrome://` addresses).

## Messages and problems

PageTurn shows no message of its own.

- **Nothing happens when I click Start Reading Mode.** The tab holds one of the browser's own pages, where no extension may act. Try on an ordinary web page.
- **Alt+P does nothing.** Another program or extension may already use that shortcut; check `chrome://extensions/shortcuts`.
- **The reading view shows the wrong part of the page, or a part is missing.** PageTurn chose the wrong block or removed too much. Leave with **Esc** and read the page normally.
- **Ghost images stay on the e-ink screen.** Tinta4PlusU must be running, connected to its helper, with the e-ink screen enabled. The refresh comes every five page turns, not at each one.


# Social Media Blocker

*Chrome and Firefox extension 1.1*

## What it is

Social Media Blocker counts the time you really spend on twenty social media and video sites and closes them all once your limit for the day is reached. You can also close them at once, with one button. To open them again you must solve five maths problems of rising difficulty: enough to break the reflex, not enough to lock you out.

The list of sites is fixed, and the limit is one total for all of them together. There is no password, no timetable and no per-site limit. The extension sends nothing anywhere.

The interface is in English only.

## First start

### Installing in Chrome

1. Download the ZIP from gallaz.ch/apps and extract it.
2. Open `chrome://extensions/`.
3. Turn on **Developer mode**.
4. Choose **Load unpacked** and select the extracted folder.

### Installing in Firefox

Firefox 128 or later is needed. The folder holds two description files, one for Chrome (`manifest.json`) and one for Firefox (`manifest.firefox.json`); Firefox needs a package where its own file bears the name `manifest.json`. A script in the folder builds that package:

1. In a terminal opened in the extracted folder, run `bash package.sh firefox`. It creates `social-blocker-firefox.zip` (the `zip` program must be present on the computer).
2. In Firefox, open `about:debugging#/runtime/this-firefox`.
3. Choose **Load Temporary Add-on** and pick `social-blocker-firefox.zip`.

An add-on loaded this way is temporary: Firefox removes it when it closes.

### What the extension is allowed to do

- See which site is in the tab in front of you, to count the time. It keeps no list of what you visit.
- Keep its own settings in the browser.
- Wake up at regular intervals to add up the time.
- Know when you are away from the keyboard and mouse, to stop counting.
- Redirect the listed sites to its own page when they are blocked.

The permission it requests covers all websites; it acts only on the listed sites.

No account is asked. After installation nothing is blocked and nothing is counted: the window shows **Status: Not Blocking** and a limit of 60 minutes.

## The screens

### The extension's window

Click the extension's icon in the browser's toolbar. The window, titled **Social Media Blocker**, has three states.

**Not blocking** (green line **Status: Not Blocking**):

- **Daily usage limit (minutes)**: the number of minutes allowed per day, 60 at first. The arrows of the field go from 1 to 1440; an empty field counts as 60.
- **Start Tracking Usage**: starts counting, from zero, with that limit.
- **Block Now**: blocks all the sites at once.
- At the bottom, a reminder: "Tracks time spent on social media & video sites. Blocks them when you hit the limit or press Block Now. Solve 5 math problems to unblock."

**Counting** (yellow line, for example **Tracking: 12m 40s / 60 min**):

- A bar fills as the time is used, with the same figures under it, for example **12m 40s / 60 min used**. The window refreshes every five seconds.
- **Stop Tracking**: stops counting.
- **Block Now**: blocks all the sites at once.
- The limit field is hidden while counting.

**Blocked** (red line **Status: BLOCKED**):

- **Unblock (Solve Math)**: opens a new tab with the maths challenge already started. It is the only button.

### The blocked page

When the sites are blocked, opening any of them shows this page instead (tab title **Site Blocked**): **This site is blocked**, "Social media and video sites are currently blocked.", "To unblock, you must solve 5 increasingly difficult math problems.", and the button **Start Math Challenge**.

### The maths challenge

- A bar and the line **Question 1 of 5** show how far you are.
- The level is named: **Difficulty: Easy**, **Difficulty: Medium**, **Difficulty: Hard**, **Difficulty: Very Hard**, **Difficulty: Expert**.
- Type the answer, a number, in the field **Your answer...** and press **Submit** or the Enter key.
- **Correct!** leads to the next question. **Wrong answer. Try again.** leaves the same question in place; there is no penalty and no limit on attempts. After two wrong answers to the same question a line beginning with **Hint:** appears.
- After the fifth correct answer: **Sites Unblocked!**, "You solved all 5 problems. Social media is now accessible.", "Close this tab and browse freely."

The five levels:

| Question | Level | Kind of problem |
|---|---|---|
| 1 | Easy | An addition and a multiplication in one line (multiply first) |
| 2 | Medium | A percentage of a number, or a product minus a square |
| 3 | Hard | A power minus a number, or a first-degree equation to solve for x |
| 4 | Very Hard | The larger root of a second-degree equation, a square root plus a number, or two equations with x and y |
| 5 | Expert | The sum of an arithmetic series, a remainder ("mod"), a number of arrangements, or the sum of the roots of a second-degree equation |

The numbers are drawn at random each time. Reloading the page starts again at question 1 with new problems.

## How to

### Give yourself a daily limit

1. Open the extension's window.
2. Type the number of minutes in **Daily usage limit (minutes)**.
3. Press **Start Tracking Usage**.

When the time is used up, all twenty sites are blocked, the tabs where one of them is open switch to the blocked page, and counting stops.

### See how much time is left

Open the extension's window: the status line and the bar show the time used and the limit.

### Block the sites right now

Open the window and press **Block Now**. It works whether or not counting is on.

### Open the sites again

1. Open the window and press **Unblock (Solve Math)**, or press **Start Math Challenge** on the blocked page.
2. Answer the five questions.
3. Close the tab.

The sites are open again and the counter is back to zero. Counting does not start again by itself: press **Start Tracking Usage** if you want the limit to apply again.

### Change the limit

1. Press **Stop Tracking**.
2. Type the new number of minutes.
3. Press **Start Tracking Usage**. The counter starts again from zero.

### Stop counting

Press **Stop Tracking**. No maths is asked for this.

### Know what is counted

- Time is added in steps of five seconds, while one of the listed sites is in the tab in front of you, in the browser window you are using.
- It is not counted for tabs in the background, when the browser is not the window in use, when the browser reports that keyboard and mouse have been idle for 60 seconds, or when the computer is locked. It resumes when you come back.
- A new day starts the counter at zero. The extension looks for the change of day when the browser starts and every half hour; the day changes at midnight in universal time (UTC), not at midnight on your clock.
- If the sites are blocked when the day changes, they are opened again and counting restarts with the same limit. This is also true of a block started with **Block Now**: it lasts until the change of day at the latest.

### Know which sites are concerned

Facebook, Twitter and X (twitter.com, x.com), Instagram, LinkedIn, Snapchat, Reddit, Tumblr, Pinterest, Threads (threads.net), Mastodon (mastodon.social only), Bluesky (bsky.app), Discord, YouTube (youtube.com, youtu.be), TikTok, Rumble, Twitch, Dailymotion, Vimeo, Telegram (telegram.org) and WhatsApp (whatsapp.com), with all their sub-addresses (for example the mobile or web versions).

## Settings

| Setting | What it changes | Choices | At first |
|---|---|---|---|
| **Daily usage limit (minutes)** | The total time allowed per day on the twenty sites together | A number of minutes (the field's arrows go from 1 to 1440) | 60 |

## Your data

Everything stays in the browser, on your computer: whether the sites are blocked, your limit, the time used today, whether counting is on, and the date of the last return to zero. No list of visited pages is kept. Nothing is sent over the network; there is no account, no statistics, no third party.

Removing the extension removes these few values with it.

## Limits

- The list of sites cannot be changed, and no site can be exempted.
- One total for all sites; no limit per site, no timetable, no different limit by day of the week.
- **Stop Tracking** needs no maths, and so does turning the extension off in the browser: the extension is a brake on a reflex, not a lock.
- After the maths, counting is not switched on again by itself.
- Only pages opened as such are blocked: a video from one of these sites embedded inside another site's page still plays.
- It acts in the browser where it is installed, not in other browsers or in apps.

## Messages and problems

- **Please enter a number.** The answer field holds something that is not a number. Answers are numbers only; a decimal point is accepted.
- **Wrong answer. Try again.** The same question stays; after two errors a hint is shown.
- **Hint: …** A pointer to the method to follow.
- **The sites opened again by themselves in the morning.** That is the change of day: the block is lifted and counting restarts with your limit.
- **I solved the problems and the limit no longer applies.** Press **Start Tracking Usage** again.
- **In Firefox the extension has disappeared.** A temporary add-on is removed when Firefox closes; load it again.


# eInk Reader

*Linux 0.6.eInk*

## What it is

eInk Reader is an e-book reader for the computer, made for the e-ink screen of the Lenovo ThinkBook Plus. It keeps a library of your books with their covers and opens EPUB, MOBI, FB2, PDF and comic-book files, and a few more formats when extra components are present.

What sets it apart: text is shown in whole pages only, one or two at a time, never as a scrolling column; and while you read, it asks Tinta4PlusU to clear the ghost images of the e-ink screen, once every ten page turns.

It is a variant of the reader Lector, and still carries that name in several places: the window is titled **Lector**, and its files are kept in folders named `Lector`.

It does not synchronise anything between computers and has no account. Its interface exists in several languages, but only partly: with a computer set to another language than English, many labels remain in English.

## First start

### Installing

The installer is written for Ubuntu and systems derived from it.

1. Download the ZIP from gallaz.ch/apps and extract it.
2. Open a terminal in the extracted folder and run `sudo bash installer.sh`.

The installer adds the components the reader needs, copies the program to `/opt/eink-reader`, creates the command `eink-reader` and adds **eInk Reader** to the applications menu. It writes what it does to `/tmp/eink-reader-install.log`.

To remove the program: `sudo bash installer.sh --uninstall`.

### Which formats you get

| Format | Files | Available |
|---|---|---|
| EPUB | `.epub` | After installation |
| Kindle | `.mobi`, `.azw`, `.azw3`, `.azw4`, `.prc` | After installation |
| FictionBook | `.fb2`, `.fb2.zip` | After installation |
| Comic books | `.cbz`, `.cbr` | After installation; compressed `.cbr` files also need the `unrar` program |
| PDF | `.pdf` | If the installer managed to add PyMuPDF (it says so, or warns "PDF support will not be available.") |
| DjVu | `.djvu` | Only if the Python component for DjVu (python-djvulibre) is on the computer; the installer does not add it |
| Markdown | `.md` | Only if the Python component `markdown` is on the computer; the installer does not add it |
| Plain text | `.txt` | Only if the Python component `textile` is on the computer; the installer does not add it |

A format whose component is missing is simply not offered: its files do not appear in the file chooser and are not found when folders are scanned.

### What you see the first time

Start **eInk Reader** from the applications menu, or type `eink-reader` in a terminal. The reader asks for nothing: no permission, no account. The window shows one tab, **Library**, empty, with a toolbar above it.

For the ghost-clearing to work, Tinta4PlusU must be running, connected to its helper, with the e-ink screen enabled. Without it the reader works the same, minus the clearing.

## The screens

### The library

The **Library** tab is always the first tab. Its toolbar holds, from left to right (the names are the tips shown when the pointer rests on a button):

- **Add book**: choose one or more files to add to the library.
- **Delete book**: remove the selected books from the library.
- **View as covers** and **View as table**: the two ways of showing the library.
- **Scan Library**: look through the library folders chosen in the settings for new books.
- **Filter library**: a menu with one line per library folder, a line **Manually Added** for books added by hand, and **All**. Untick a line to hide its books.
- **Library background color**: the colour behind the covers.
- **Settings**: opens the settings window on its **Library** page.
- **About**: opens the settings window on its **About** page.
- On the right, the search field **Search for Title, Author, Tags...**: type to keep only the books whose title, author, tags, folder or file name contain the text. The Esc key empties it.
- The box **Sort by**, in the cover view only: **Title**, **Author**, **Year**, **Newest** (last added first), **Last Read** (last opened first; books never opened are hidden), **Progress** (most advanced first; books not started are hidden).

In the cover view each book is its cover. A small mark at the bottom right of a cover shows the progress: a pie that fills as you read, a tick when the book counts as read, a warning sign (and a paler cover) when the file is no longer where it was. Resting the pointer on a cover shows the title, the author and the year.

The table view has the columns **Title**, **Author**, **Year**, **Last Read** (time since the book was last opened, such as `3d`, `5h`, `12m` or `<1m`), **%** (the same progress mark) and **Tags**. Click a column's heading to sort by it.

In both views:

- Double-click a book to open it in a new tab.
- Right-click a book for the menu: **Start reading**, **Edit** (when a single book is selected), **Delete**, **Mark read**, **Mark unread**.
- Drop files from the file manager onto the library to add them.
- Several books can be selected at once.

A line at the bottom of the window appears while you search (it shows the number of books), while books are being added (**Adding books...** and a progress bar) and during a scan (**Checking library folders**, then **Parsing files**). When a file could not be read, a warning button appears there; click it to open the log.

### The window "Edit metadata"

**Edit** in a book's menu opens a small window with the cover and four fields: **Title**, **Author**, **Year**, **Tags** (comma separated).

- Click the cover (**Cover (click to change)**) to choose another picture, a `.jpg` or `.png` file.
- The tick button (**OK**), or the Enter key in a field, saves. The cross button (**Cancel**) closes without saving.
- The colour button changes the background colour of this kind of small window.
- If the year is not a number, the former year is kept.

### A book in pages (EPUB, MOBI, FB2, Markdown, text)

Each open book has its own tab, with its cover and title. The toolbar changes to:

- **View settings**: replaces the buttons below with the appearance controls (see further down); click again to come back.
- **Add bookmark**: marks the current place.
- **Bookmarks (Ctrl + B)**, **Annotations (Ctrl + N)**, **Search (Ctrl + F)**: open the side panel on that tab.
- **Toggle distraction free mode (Ctrl + D)**: hides the toolbar and the tabs.
- **Fullscreen (F)**: the book alone on the whole screen.
- On the right, the **Table of Contents** box: choose a chapter to go to it.

Moving through the book:

| Action | Effect |
|---|---|
| Down arrow, or mouse wheel down | Next page; after the last page of a chapter, the next chapter |
| Up arrow, or mouse wheel up | Previous page; before the first page of a chapter, the previous chapter |
| Right arrow | Next chapter |
| Left arrow | Previous chapter |
| Space | Forward by one screen; at the end of a chapter, a second press goes to the next chapter |
| F | Full screen on and off |
| Esc | Closes the side panel or the note if one is open, otherwise leaves full screen |

The Up and Down arrows turn pages in **Single page** only; in **Double page**, turn the pages with the mouse wheel.

Right-click in the text for the menu:

- **View** › **Single page** or **Double page**. Every book opens in single page.
- **Exit fullscreen**, or **Exit Distraction Free mode**, when one of them is on.
- With text selected: **Define "word"** (the first selected word), **Search for "…"** › **In this book**, **Google**, **Wikipedia**, **Youtube**, and **Annotate** › the list of your annotation styles (or **&lt;No annotations set&gt;**).
- With nothing selected: **Search**.
- On a passage already annotated: **Annotation** › **Edit note**, **Delete annotation**.
- **Add Bookmark**: a bookmark at the place you clicked.
- In full screen or distraction-free mode, also **Bookmarks** and the table of contents.

The mouse pointer disappears after two seconds without movement.

### A book in images (PDF, DjVu, comics)

PDF, DjVu and comic-book files are shown as pictures of their pages. The toolbar is the same without **Annotations** and **Search**.

| Action | Effect |
|---|---|
| Down and Up arrows | Move within the page by a small step; at the bottom or top, go to the next or previous page |
| Space | Move down by a large step; at the bottom, next page |
| Right and Left arrows | Next and previous page |
| Mouse wheel | Moves within the page, then changes page at the bottom or top |
| Hold the mouse button and move | Drags the page |
| D | Double page on and off |
| M | Manga mode on and off |
| + (or =) and - | Zoom in and out |
| W, B, O | Fit to width, best fit, original size |
| F, Esc | Full screen on, off |

Right-click on the page for the menu: **Save page as...** (saves the page as a `.png`, `.jpg` or `.bmp` picture), **View** › **Double page mode (D)**, **Manga mode (M)**, **Invert page colors**, **Zoom in (+)**, **Zoom out (-)**, **Fit width (W)**, **Best fit (B)**, **Original size (O)**; and, when relevant, **Exit fullscreen**, **Exit Distraction Free mode**, **Bookmarks** and the table of contents.

### The appearance controls

Press **View settings**. For a book in pages, the toolbar shows:

- A box with **Profile 1**, **Profile 2**, **Profile 3**: three sets of appearance you can switch between. Every change below is stored in the profile shown.
- The typeface box and the **Font size** box (8 to 46 in steps of 2, then 56, 64 and 72).
- **Text color** and **Background color**.
- **Increase line spacing** and **Decrease line spacing**.
- **Increase padding** and **Decrease padding**: the margins on the left and right.
- **Left align text**, **Right align text**, **Center align text**, **Justify text**.
- **Reset profile**: gives the profile shown its original values.

The three profiles as delivered:

| Profile | Typeface | Text | Background |
|---|---|---|---|
| Profile 1 | Noto Sans Fallback | Black | Light grey |
| Profile 2 | Roboto | Light grey | Near black |
| Profile 3 | Clear Sans | Grey-blue | Dark blue |

All three start with size 30, justified text, margins of 150 and line spacing of 110.

For a book in images, the toolbar shows instead: **Double page mode (D)**, **Manga mode (M)** (in double page, the right-hand page comes first), **Invert page colors**, **Rotate image clockwise**, **Rotate image anti-clockwise** (turning the page switches double page off), **Zoom in (+)**, **Zoom Out (-)**, **Fit Width (W)**, **Best Fit (B)**, **Original size (O)** and **Background color**. As delivered: best fit on a black background.

### The side panel

The panel opens on the right, over the book, with three tabs (one only, **Bookmarks**, for a book in images).

- **Bookmarks**: your bookmarks, grouped by chapter. Click a bookmark to go there, a chapter's name to go to its beginning. Right-click a bookmark for **Edit** (rename it) and **Delete**.
- **Annotations**: the list of your annotation styles. Double-click a style, then select text in the book: the style is applied to it.
- **Search**: type in the field **Search**. Three buttons refine it: **Search entire book** (otherwise only the current chapter is searched), **Match case**, **Match word**. Results are listed by chapter; click one to go there, with the found text selected. The field turns red when nothing is found.

### The navigation bar

When **Show navigation bar** is ticked in the settings, moving the mouse over a book shows a small bar at the bottom right: previous chapter, table of contents, next chapter. It hides again after two seconds.

### The definition window

**Define** in the text menu asks an online dictionary for the selected word and shows the word, its root and its definitions by category. Three buttons: close, **Play pronunciation of root word**, and the background colour. When nothing is found the window says **No definitions found in** followed by the language code (for example EN).

### The settings window

The **Settings** window has four pages listed on the left: **Library**, **Switches**, **Annotations**, **About**. They are described under Settings below.

## How to

### Add books

- Press **Add book** (or Ctrl+O) and choose the files; or
- drop the files onto the library; or
- declare a library folder (see below) and let the reader find them.

A book already in the library is not added twice. Books are not copied: the library remembers where each file is.

### Declare library folders

1. Open **Settings**; the **Library** page shows the folders of the computer.
2. Tick the folders that hold your books. Their sub-folders are included.
3. Optionally, double-click in the **Name** column to give the folder a name (it appears in the **Filter library** menu), and in the **Tags** column to give tags to all its books (the search finds them).
4. Press **Scan Library**.

The scan adds the new books and removes from the library the books that are no longer in a ticked folder; books added by hand stay. **Close** leaves the window without scanning and forgets the changes made to the folders.

### Open a book and come back to it

Double-click it. The book opens where you left it. Position, bookmarks and annotations are saved when you close the tab or quit the reader. If **Remember open files** is ticked, the books open when you quit are opened again at the next start.

### Read on the e-ink screen

1. Start Tinta4PlusU and enable the e-ink screen.
2. Open the book and press **F** for full screen.
3. Turn pages with the Down arrow or the mouse wheel.

The reader counts each page turned with the arrows or the wheel and each change of chapter (or of page, in a book in images); every tenth time, it asks Tinta4PlusU for a full refresh of the screen. In a book in pages, moving with the Space bar inside a chapter is not counted.

### Change the look of the text

Press **View settings**, choose a profile, then the typeface, size, colours, spacing, margins and alignment. Press **View settings** again to get the normal toolbar back.

### Read two pages side by side

Text: right-click, **View** › **Double page**. Images: press **D**.

### Put a bookmark and find it again

Press **Add bookmark**, or right-click the exact place and choose **Add Bookmark**. The side panel opens with the new bookmark, named **New bookmark**, ready to be renamed. Later, press Ctrl+B and click it.

### Highlight a passage

1. Create a style once: **Settings** › **Annotations** › **New**, give it a name and tick what it does (see Settings).
2. In the book, select the passage, right-click, **Annotate**, and choose the style. Or press Ctrl+N, double-click the style, then select the passage.

To add a note to it: right-click the passage, **Annotation** › **Edit note**, type in the **Note** window; the note is kept when the window closes (Esc). To remove the highlight: **Annotation** › **Delete annotation**.

### Search in a book

Press Ctrl+F and type. Or select a word, right-click, **Search for** › **In this book**.

### Look a word up

Select that single word, right-click, then **Define**, or **Search for** › **Google**, **Wikipedia** or **Youtube**, which open your web browser.

### Mark a book read or unread

Right-click it in the library: **Mark read** or **Mark unread**. **Mark unread** also sends the book back to its beginning.

### Correct a title, an author, a cover

Right-click the book, **Edit**.

### Remove a book

Select it and press **Delete book** (or the Delete key), then answer **Yes** to **Delete book(s)?**. The book leaves the library; the file itself is not deleted.

### Save a page of a comic or PDF as a picture

Right-click the page, **Save page as...**.

## Settings

### Page "Switches", group "Library"

| Setting | What it changes | At first |
|---|---|---|
| **Consider book read at percent** | The progress from which a book gets the "read" tick; 90 or more | 95 |
| **Icon theme:** **Dark** / **Light** | The colour of the toolbar icons. "Restart application to see changes" | Dark |
| **Startup: Refresh library** | Scans the library folders each time the reader starts | Off |
| **Remember open files** | Reopens at start the books that were open when you quit | On |
| **Cover shadows** | Draws a shadow behind each cover | On |
| **Load covers only when needed** | Loads only the covers in view. "Enabling reduces startup time and memory usage" | On |
| **Generate tags from files** | Takes the tags written inside the book files when adding them | On |
| **Shrink long book titles** | Cuts tab titles longer than 30 characters | Off |
| **Show navigation bar** | Shows the navigation bar over books opened afterwards | Off |
| **Download missing covers** | "Attempt to download missing book covers from Google books - SLOW". Applies when books are added | Off |

### Page "Switches", group "Reading"

| Setting | What it changes | At first |
|---|---|---|
| **Hide scrollbars when reading** | Hides the scroll bars. "Horizontal scrolling with Alt + Scroll", "Reopen book to see changes" | Off |
| **Cache comic / pdf pages** | Prepares neighbouring pages in advance. "Greatly reduces page transition time at the cost of more memory" | On |
| **Small increment** | Books in images: number of presses on Up or Down to cross a page; 4 to 10 | 4 |
| **Large increment** | Books in images: number of presses on Space to cross a page; 1 to 10 | 2 |
| **Dictionary language** | Language used by **Define**: **English**, **Spanish**, **Hindi** | English |
| **Scroll speed** | Speed of scrolling inside a page; slider from 3 to 15 | 7 |

### Page "Library"

The folder tree described under "Declare library folders", with the buttons **Scan Library** (its tip: "Save changes and start library scan") and **Close**.

### Page "Annotations"

The list of your annotation styles, with the buttons **New**, **Delete**, **Edit**, **Move Up** and **Move Down**, and a preview. **New** and **Edit** open the **Annotation Editor**:

- **Annotation Name**: the name of the style (it cannot be empty).
- **Type**: **Text markup**, the only kind.
- **Foreground**, with its colour button: the colour of the text.
- **Highlight**, with its colour button: the colour behind the text.
- **Bold**, **Italic**.
- **Underline**, with the kind of line (**Solid**, **Dashes**, **Dots**, **Wavy**) and its colour.
- **OK** saves the style, **Cancel** abandons.

### Page "About"

Two tabs: **About** (the name Lector, the version and the original author) and **Log** (the reader's journal). Two buttons:

- **Clear Log** empties the journal.
- **Reset Application** asks **Delete database and exit?**; **Yes** erases the whole library (books listed, positions, bookmarks, annotations in books) and quits. The book files are not touched.

### Kept without a setting

The reader also remembers the size of the window, the view (covers or table), the library's background colour, the three profiles, the zoom and background for books in images, and the double-page, manga and inverted-colours switches.

## Your data

- Your books stay where they are on the disk. The library keeps, in the file `~/.local/share/Lector/Lector.db`, each book's title, author, year, tags, cover, reading position, bookmarks and annotations.
- The settings are in `~/.config/Lector/Lector.conf`, the journal in `~/.local/share/Lector/Lector.log`.
- Uninstalling the program leaves these three files in place.
- There is no synchronisation, export or import.

The reader uses the network in three cases only, each started by you:

- **Download missing covers**, when ticked: the title of each book without a cover is sent to Google Books.
- **Define**: the selected word is sent to an online dictionary service (Oxford Dictionaries); the pronunciation, if you play it, is fetched from the address that service gives.
- **Search for** › **Google**, **Wikipedia**, **Youtube**: the selected text is handed to your web browser.

On the computer itself, the reader sends Tinta4PlusU the request to refresh the e-ink screen; nothing about the book is in it.

## With the other apps

- **Tinta4PlusU**: receives the refresh request every ten page turns. If it is not running, the request is dropped silently.
- **Files**: the applications menu entry lets the file manager offer eInk Reader for PDF, EPUB, Kindle and comic-book files.

## On the computer

Keyboard shortcuts valid everywhere in the reader:

| Shortcut | Effect |
|---|---|
| Ctrl+O | Add books |
| Ctrl+W | Close the current book's tab |
| Ctrl+D | Distraction-free mode on and off |
| Ctrl+Q | Quit |
| Delete | In the library, remove the selected books |

In a book: Ctrl+B (bookmarks), Ctrl+N (annotations), Ctrl+F (search), F (full screen), Esc, and the keys listed with each kind of book above.

From a terminal:

- `eink-reader book.epub other.pdf` adds the named files to the library and opens them.
- `eink-reader debug` starts with a detailed journal, after emptying the previous one.

## Limits

- No scrolling mode for text.
- The ghost-clearing comes every ten page turns, not at each page, and only through Tinta4PlusU on a ThinkBook Plus.
- **Double page** for text is not remembered: each book opens in single page.
- PDF and DjVu pages are pictures: no text selection, no search, no annotations, no definitions in them. The same goes for comics.
- Links inside a book do nothing when clicked.
- A Markdown or text file is one single chapter; its title is the file name.
- The dictionary knows English, Spanish and Hindi only.
- The interface is only partly translated, and the program calls itself Lector.

## Messages and problems

- **Delete book(s)?** (window **Confirm deletion**): confirms removing the selected books from the library.
- **Delete database and exit?** (window **Confirm**): see **Reset Application**.
- **Adding books...**, **Checking library folders**, **Parsing files**: the reader is at work; wait for the line to disappear.
- **Library scan in progress...**: shown on the scan button while a scan runs; a second scan cannot be started before the first ends.
- **No definitions found in EN** (or ES, HI): the dictionary service gave no answer for that word, or could not be reached.
- **&lt;No annotations set&gt;**: you have not created any annotation style yet.
- **A warning button at the bottom of the window**: a file could not be read. Click it: the **Log** tab names the file, for example "Unsupported extension: …" or "Error initializing: …".
- **My PDF, DjVu, Markdown or text files are not offered.** The component for that format is missing; see "Which formats you get". At start, the journal says for instance "pymupdf is not installed. Will be unable to load PDF files."
- **A cover is pale with a warning sign.** The file was moved, renamed or deleted. Put it back, or remove the book and add it again from its new place.
- **Scan Library opens the settings instead of scanning.** No library folder is ticked yet.
- **The e-ink screen keeps ghost images.** Check that Tinta4PlusU is running with the e-ink screen enabled; the refresh comes after ten page turns.
- **The installer stops with "This installer must be run as root (sudo bash installer.sh)".** Start it with `sudo`.
- **The installer ends with "Missing dependencies:".** It lists what could not be installed; the formats that depend on it will be missing.


# Tinta4PlusU

*Linux 0.1.0 alpha · Lenovo ThinkBook Plus Gen 4 IRU*

## What it is

Tinta4PlusU drives the colour e-ink screen on the lid of the Lenovo ThinkBook Plus Gen 4 IRU under Linux. From one small window you switch the computer from its OLED screen to the e-ink screen and back, clear the ghost images, choose between a fast and a clean display mode, and set the frontlight.

It is made of two parts: the window you see, and a helper that works with administrator rights, because the e-ink screen's controller and the frontlight can only be reached that way. The window starts the helper and asks for your password when it does.

It is an experimental program, a variant of Tinta4Plus by Jon Cox. It writes directly to the laptop's hardware, was developed without any documentation from Lenovo or E Ink, and comes with no warranty: its own licence text warns that it can make the hardware misbehave. It works on this one laptop model only.

The interface is in English only.

## First start

### What is needed

- A Lenovo ThinkBook Plus Gen 4 IRU.
- Ubuntu 24.04 or later, or a system derived from it (Xubuntu, Kubuntu, Linux Mint).
- One of these desktops: GNOME, Cinnamon, XFCE or KDE Plasma. Only GNOME and XFCE in an X11 session have been properly tested; GNOME and KDE Plasma under Wayland, Cinnamon and KDE Plasma under X11 are supported but may have issues.
- For the frontlight: Secure Boot turned off in the BIOS. The e-ink screen itself works with Secure Boot on.

### Turning Secure Boot off

1. Restart the laptop and press **Enter** repeatedly right after power-on to get the boot menu.
2. Press the function key that opens the BIOS settings.
3. Go to **Security**, then **Secure Boot**, and set it to **Disabled**.
4. Save and restart.

Turning Secure Boot off lowers the protection of the computer at start-up; the licence text says so.

### Installing

1. Download the ZIP from gallaz.ch/apps and extract it.
2. Open a terminal in the extracted folder and run `sudo bash installer.sh`.
3. At **Choose installation mode [1/2]:** answer **2** (Python scripts). Choice 1 (compiled binary) is only available after building the program yourself with `bash build.sh`.
4. At **Install PolicyKit policy? [y/N]** answer **y** to avoid, in the installer's words, "re-entering your password every time the helper daemon starts"; the first start still asks for it. The default answer is no.

The installer recognises your desktop, adds the components needed, copies the program to `/opt/tinta4plusu`, creates the command `tinta4plusu`, adds **Tinta4PlusU** to the applications menu and makes it start at each login. It writes what it does to `/tmp/tinta4plusu-install.log`.

At the end it checks what is missing. If it warns that neither `feh` nor `imv` was found, install one of them (`sudo apt install feh` for an X11 session, `sudo apt install imv` for Wayland): the program needs one to show the privacy image described below.

To remove the program: `sudo bash installer.sh --uninstall`.

### The first launch

Start **Tinta4PlusU** from the applications menu, or type `tinta4plusu` in a terminal.

1. A window **End User License Agreement** opens ("Please read carefully"). Read the text to the end: the **Agree** button only becomes available once you have scrolled to the bottom. **Disagree** closes the program. The window cannot be closed any other way. Your agreement is remembered; the window does not come back.
2. The main window opens and starts the helper: the system asks for your password.
3. When the status line reads **Status: Connected to helper daemon**, the program is ready. Nothing has changed on the screens yet: the big button reads **eInk Disabled**.

When the program is started automatically at login, it does not start the helper, so that no password is asked at that moment. The status line reads **Status: Click 'Connect to Helper' to start**; press **Connect to Helper** when you want to use the e-ink screen.

## The screens

### The main window

The window is titled **ThinkBook E-Ink Control**. From top to bottom:

- The **status line**, beginning with **Status:**, says what the program is doing.
- The **Secure Boot** indicator: **Secure Boot: OFF** on green, **Secure Boot: ON** on red, or **Secure Boot: Unknown** on grey.
- **Connect to Helper**: starts the helper, or reconnects to it. It is greyed out once connected.

The frame **Display Control**:

- The big button, orange with **eInk Disabled** or green with **eInk Enabled**: switches from one screen to the other. During the countdown it reads **Flip now... 5**, then 4, 3, 2, 1.
- **Refresh eInk (Clear Ghosts)**: redraws the whole e-ink screen once to remove ghost images.
- **Set Dynamic**: the fast mode, for scrolling and moving things, with more ghosting.
- **Set Reading**: the clean mode, for text, slower and with less ghosting.
- **Refresh period (s):** a slider from 0 to 60, in steps of 5. Above 0, the program clears the ghosts by itself at that interval, in seconds.
- **Display Scale:** a slider from 1.00 to 2.00, in steps of 0.05: how large things are drawn on the e-ink screen.
- **Autoswitch theme (HighContrast ↔ Adwaita-dark)**: when ticked, the desktop takes a high-contrast theme on the e-ink screen and a dark theme back on the OLED.

The three buttons **Refresh eInk (Clear Ghosts)**, **Set Dynamic** and **Set Reading** are greyed out while the e-ink screen is off.

The frame **Frontlight Control**:

- **Brightness (0-8):** a slider for the light of the e-ink screen, 0 being off. When the helper connects, the slider takes the value the laptop actually has.
- With Secure Boot on, a red notice appears here and the slider is greyed out: "⚠ Secure Boot is enabled. Frontlight controls disabled. Please disable Secure Boot in BIOS (Press ENTER during boot)."

The frame **Activity Log** lists, with the time, everything the program does: successes in green (lines with ✓), errors in red (lines with ✗ or ⚠).

At the bottom: **Version 0.1.0 alpha**, and **Buy Me A Coffee**, which opens in your web browser the donation page of the original author.

### The floating refresh button

While the e-ink screen is on, a square light-blue button with a circular arrow (⟳) floats on the left edge of the screen, halfway down, half transparent and above all windows. Click it to clear the ghosts. Drag it to put it elsewhere. It goes away when you return to the OLED. Under Wayland it may be missing; the log then says "Floating refresh button unavailable (Wayland limitation)".

### The privacy image

An e-ink screen keeps its last picture when it is switched off. So that your last window does not stay readable on the lid, the program fills the e-ink screen with one of three pictures, chosen at random, just before switching it off.

## How to

### Switch to the e-ink screen

1. Press **eInk Disabled**.
2. The log says "Flip your screen to eInk now!" and the button counts down five seconds: turn the screen over during that time.
3. Wait for the button to turn green and read **eInk Enabled**.

In order, the program turns the e-ink screen on at the chosen scale, lights the frontlight at the slider's level, sets the fast mode (Dynamic), turns the OLED off and attaches the touch layer to the e-ink screen. If **Autoswitch theme** is ticked, the desktop takes the high-contrast theme.

### Return to the OLED screen

1. Press **eInk Enabled**.
2. The log says "Flip your screen to OLED now!" and the button counts down five seconds.
3. The e-ink screen shows the privacy image for about three seconds; then the frontlight and the e-ink screen go off, and the OLED comes back with the scale it had before.

Closing the program's window while the e-ink screen is on does the same thing first, without the countdown.

### Clear ghost images

Any of these, while the e-ink screen is on:

- press **Refresh eInk (Clear Ghosts)**;
- click the floating ⟳ button;
- press the **Help** key of the keyboard (Fn+F9);
- set **Refresh period (s):** above 0 to have it done at regular intervals.

### Read comfortably, or scroll comfortably

Press **Set Reading** before reading text; press **Set Dynamic** before scrolling or working with windows. The e-ink screen is in Dynamic mode each time it is switched on.

### Set the frontlight

Move the **Brightness (0-8):** slider. Or, while the e-ink screen is on, use the brightness keys of the keyboard (Fn+F6 for more, Fn+F5 for less): they then act on the frontlight, one level per press.

### Make everything larger or smaller on the e-ink screen

Move the **Display Scale:** slider. The log confirms "will apply on next display switch": the new scale is used the next time you switch to the e-ink screen. Under GNOME with Wayland, the nearest scale the system accepts is used.

### Check the touch layer

The downloaded folder contains a test tool that is not installed with the rest. With the e-ink screen on, run `python3 touch_diagnostic.py` from that folder: it shows nine targets to tap and reports the gap between each target and where the touch was registered.

## Settings

| Setting | What it changes | Choices | At first |
|---|---|---|---|
| **Refresh period (s):** | Interval of the automatic ghost-clearing | 0 (never) to 60 seconds, by 5 | 0 |
| **Display Scale:** | Size of everything on the e-ink screen | 1.00 to 2.00, by 0.05 | 1.00 |
| **Autoswitch theme (HighContrast ↔ Adwaita-dark)** | Changes the desktop theme with the screen | Ticked or not | Not ticked |
| **Brightness (0-8):** | Frontlight level | 0 to 8 | The level the laptop has |

The first three are remembered from one session to the next. The brightness is not stored by the program: it is read from the laptop.

Under KDE Plasma, the two themes are the colour schemes Breeze High Contrast and Breeze Dark.

One value has no control in the window: the length of the countdown before a switch, 5 seconds. It is the line `flip_countdown` of the settings file; 0 removes the countdown.

## Your data

The program uses no network and has no account. The only thing it opens on the internet is the donation page, when you press **Buy Me A Coffee**.

- Settings: the file `~/.config/Tinta4PlusU/settings`. Your agreement to the licence: the empty file `~/.config/Tinta4PlusU/agree`.
- Journals, rewritten at each start: `/tmp/tinta4plusu.log` (the window) and `/tmp/TintaHelper.log` (the helper).
- Uninstalling removes the program, its menu and start-up entries and the PolicyKit policy; it leaves the folder `~/.config/Tinta4PlusU`.

While the helper runs, other programs on the same computer can ask it things: any program run by any user of the computer can send it the same commands as the window, and any web page open in a browser on the computer can ask for a ghost-clearing (nothing else). This is how eInk Reader and PageTurn work with it.

## With the other apps

- **eInk Reader** asks for a ghost-clearing every ten page turns.
- **PageTurn** (the Chrome extension) asks for one every five page turns.

Both need the helper to be running and the e-ink screen to be on; otherwise their requests are ignored.

## On the computer

Keys that work in any program while the e-ink screen is on (they go through the helper):

| Key | Effect |
|---|---|
| Help (Fn+F9) | Clear ghost images |
| Brightness up (Fn+F6) | Frontlight one level up |
| Brightness down (Fn+F5) | Frontlight one level down |

The command `tinta4plusu --autostart` starts the window without starting the helper; it is what the login entry uses.

The helper stops by itself when it has heard nothing from the window for 60 seconds. If the window loses the helper, it says **Status: Helper disconnected - attempting restart...** and starts it again; the password may be asked.

After the laptop wakes from sleep, and three seconds after the program starts, it checks that the right screen is on, at the right size, with the keyboard layout and the touch layer as they should be, and corrects what is wrong. What it corrected appears in the log on a line beginning with "↻ Post-resume:" or "Startup check:".

## Limits

- One laptop model only: the Lenovo ThinkBook Plus Gen 4 IRU.
- Alpha quality; only GNOME and XFCE under X11 have been properly tested.
- The frontlight cannot be controlled with Secure Boot on.
- According to the licence text, it probably does not work correctly with an external monitor connected.
- If a switch back to the OLED fails, or the computer is turned off while the e-ink screen is on, the e-ink screen keeps showing its last picture until a full restart. Check the lid before leaving the laptop in view.
- The floating button may be missing under Wayland.
- The licence text shown at first launch still describes an older state of the program (Xubuntu with XFCE only); the list of supported desktops above is the current one.

## Messages and problems

- **Secure Boot Enabled** (window): "Secure Boot is currently enabled in your BIOS. Frontlight controls require direct hardware access which is blocked by Secure Boot." The window lists the steps to turn it off and adds: "Note: E-Ink display controls will continue to work normally."
- **Error** (window): "Not connected to helper daemon. Please click 'Connect to Helper' first." Press **Connect to Helper** and give your password.
- **Status: Launching helper daemon (password required)...**: the system is waiting for your password.
- **Status: Failed to launch helper: Helper process exited (code …) — password cancelled or pkexec failed**: the password was cancelled or wrong, or the desktop has nothing to ask it with. Under GNOME or Cinnamon, install it with `sudo apt install policykit-1-gnome`, then log out and in again, and press **Connect to Helper**.
- **Failed to launch helper: Helper started but socket not available after 12s**, or **Helper not found: …**: the helper did not start; reinstall the program, and look at `/tmp/TintaHelper.log`.
- **EULA Not Found**: "EULA file not found: … The application will now exit." The licence text is missing from the installation; install again.
- **Switch already in progress...**: you pressed the big button during the countdown; wait.
- **✗ Command failed: …**: the helper could not carry out an order; the line gives the reason.
- **Frontlight enable failed (readback mismatch)**, or the same for the brightness: the laptop did not confirm the value. The light is usually on all the same; look at the screen.
- **Warning: Could not display privacy image**, or **Warning: Privacy image not found: …**: install `feh` or `imv`, and check the e-ink screen before leaving the laptop.
- **⚠ Failed to enable E-Ink display on eDP-2**, and similar lines naming eDP-1 (the OLED) or eDP-2 (the e-ink screen): the desktop refused the change of screen; try again, and see whether your desktop is among the tested ones.
- **The OLED stays black after switching back.** Close the lid and open it again.
- **The laptop no longer responds, or the e-ink screen or the frontlight behave erratically.** Usually a restart is enough. If not, reset the laptop's embedded controller: turn the laptop off and unplug the charger; with a pin, hold the small reset button in the hole under the laptop, next to the fan grille, for at least 60 seconds; then hold the power button for 60 seconds; then press the power button normally (the screen can stay blank for up to a minute). Afterwards check in the BIOS that Secure Boot is still off.
- **The installer says "This installer must be run as root (sudo bash installer.sh)".** Start it with `sudo`.
- **The installer says "Installation failed at line …".** The reason is in `/tmp/tinta4plusu-install.log`. After correcting it, run the installer again; `sudo bash installer.sh --uninstall` cleans a half-finished installation.