kobobridge 0.1.0__tar.gz

kobobridge-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/

kobobridge-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Serves the eReader sync protocol in front of an Audiobookshelf library, read only.
+- Sends epub and kepub files, with covers, authors, series and descriptions.
+- Cuts large libraries into batches so a first sync completes.
+- Keeps reading progress pushed by the reader in a local file, never in Audiobookshelf.
+- No telemetry, and no call to any server other than your own Audiobookshelf.

kobobridge-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
+ENV KOBOBRIDGE_PORT=8484
+ENV XDG_DATA_HOME=/data
+VOLUME ["/data"]
+EXPOSE 8484
+
+RUN useradd --create-home --uid 10001 bridge && mkdir -p /data && chown bridge /data
+USER bridge
+
+ENTRYPOINT ["kobobridge"]
+CMD ["run", "--host", "0.0.0.0", "--port", "8484"]

kobobridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Younes Z.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kobobridge-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: kobobridge
+Version: 0.1.0
+Summary: Serve an Audiobookshelf ebook library to a Kobo eReader over the native sync protocol.
+Project-URL: Homepage, https://github.com/Rezarys/kobobridge
+Project-URL: Source, https://github.com/Rezarys/kobobridge
+Project-URL: Issues, https://github.com/Rezarys/kobobridge/issues
+Author: Younes Z.
+License: MIT License
+        
+        Copyright (c) 2026 Younes Z.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: audiobookshelf,ebook,epub,kobo,selfhosted,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Requires-Python: >=3.9
+Requires-Dist: flask>=2.2
+Requires-Dist: requests>=2.28
+Requires-Dist: waitress>=2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kobobridge
+
+```
+pip install kobobridge
+```
+
+Serves the ebooks in your [Audiobookshelf](https://www.audiobookshelf.org/) library to a Kobo eReader over the reader's own sync protocol, so books arrive over wifi instead of over a USB cable.
+
+Answers [audiobookshelf#3504](https://github.com/advplyr/audiobookshelf/issues/3504), where people have been asking for Kobo sync for ebooks.
+
+**Not affiliated with Audiobookshelf, and not affiliated with Rakuten Kobo Inc.** This is an independent project. "Kobo" is a trademark of its owner and is used here only to say which device the software talks to.
+
+## What it does
+
+Your Audiobookshelf server already holds your epubs. Your eReader already knows how to sync a library over the network. kobobridge sits between the two and answers the sync protocol on behalf of your own server:
+
+```
+  Kobo eReader  ->  kobobridge  ->  Audiobookshelf
+                    (read only)
+```
+
+- New epubs in Audiobookshelf appear on the reader after a sync.
+- Covers, authors, series and descriptions come across.
+- Reading progress from the reader is stored by the bridge.
+- Large libraries are sent in batches, so the first sync completes.
+
+## What it does not do
+
+Worth reading before you install.
+
+- **It never writes to your library.** Every call to Audiobookshelf is a GET. Reading progress the reader pushes is kept in a small file next to the bridge, not pushed into Audiobookshelf, so progress does not yet show up in the Audiobookshelf web player. A test asserts this.
+- **It does not touch any account on the manufacturer's store.** No store credential, no user key, no device id. The bridge issues its own token and never contacts the store.
+- **It does not convert anything.** Only epub and kepub files are offered. Pdf, mobi and azw3 in your library are skipped rather than converted.
+- **Audiobooks and podcasts are skipped.** The reader cannot play them.
+- **Shelves and collections are not mirrored yet.**
+- **No telemetry, no phoning home, no analytics.** Nothing about your library leaves your machine.
+
+## Setup
+
+### 1. Get an Audiobookshelf API token
+
+In Audiobookshelf: Settings, Users, pick your user, then copy the API token.
+
+### 2. Run the bridge
+
+```
+export KOBOBRIDGE_ABS_URL=http://192.168.1.10:13378
+export KOBOBRIDGE_ABS_TOKEN=paste-your-token-here
+kobobridge check
+```
+
+The `check` command lists the ebooks the reader will be offered. If that looks right:
+
+```
+kobobridge run
+```
+
+It prints the one line you need to copy.
+
+### 3. Point the reader at the bridge
+
+```
+Point the eReader at this bridge:
+
+  1. Plug the eReader into a computer over USB.
+  2. Open the hidden folder .kobo/Kobo/ and edit 'Kobo eReader.conf'.
+  3. Under [OneStoreServices], set the line below. Create that
+     section if it is not already there.
+
+       api_endpoint=http://192.168.1.10:8484/kobo/rG9x2K7pQm4vB1nT8sYw
+
+  4. Eject, then sync from the eReader.
+```
+
+Keep a copy of the original `api_endpoint` value. Putting it back returns the reader to normal.
+
+To keep the same token across restarts, set `KOBOBRIDGE_DEVICE_TOKEN` to the value the bridge printed. Otherwise a new one is generated each run and the reader has to be pointed again.
+
+## Docker
+
+```
+docker run -d --name kobobridge -p 8484:8484 \
+  -e KOBOBRIDGE_ABS_URL=http://192.168.1.10:13378 \
+  -e KOBOBRIDGE_ABS_TOKEN=paste-your-token-here \
+  -e KOBOBRIDGE_DEVICE_TOKEN=pick-a-long-random-string \
+  -v kobobridge-data:/data \
+  ghcr.io/rezarys/kobobridge:latest
+```
+
+## Settings
+
+Required:
+
+- `KOBOBRIDGE_ABS_URL`: address of your Audiobookshelf server.
+- `KOBOBRIDGE_ABS_TOKEN`: Audiobookshelf API token.
+
+Optional:
+
+- `KOBOBRIDGE_DEVICE_TOKEN`: pin the reader token instead of generating one per run.
+- `KOBOBRIDGE_PUBLIC_URL`: the address the reader sees, when behind a reverse proxy.
+- `KOBOBRIDGE_LIBRARY_ID`: sync one library instead of every book library.
+- `KOBOBRIDGE_PORT`: port to bind, default 8484.
+- `KOBOBRIDGE_TIMEOUT`: seconds to wait on Audiobookshelf, default 30.
+
+## Security
+
+The reader token is the only thing standing between the internet and your library, so:
+
+- Keep the bridge on your home network, or behind a VPN such as Tailscale or Wireguard.
+- If you do expose it, put it behind a reverse proxy with TLS and set `KOBOBRIDGE_PUBLIC_URL`. The reader sends the token in the URL, which means it lands in access logs.
+- Pin `KOBOBRIDGE_DEVICE_TOKEN` to something long and random.
+
+## Status
+
+Version 0.1.0, first release. The shapes of the sync protocol were learned by reading the long standing [Calibre-Web](https://github.com/janeczku/calibre-web) implementation, which has served this protocol since 2019. Reading only: Calibre-Web is under the GPL, this project is under the MIT licence, and no code was copied from it. The Audiobookshelf side and the batching logic are covered by tests.
+
+What has not been exercised yet is a full sync against a physical reader, because the author does not own one. If you try it, an issue saying what happened is the single most useful thing you can send, working or not.
+
+## Development
+
+```
+git clone https://github.com/Rezarys/kobobridge
+cd kobobridge
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. Younes Z.

kobobridge-0.1.0/README.md

@@ -0,0 +1,130 @@
+# kobobridge
+
+```
+pip install kobobridge
+```
+
+Serves the ebooks in your [Audiobookshelf](https://www.audiobookshelf.org/) library to a Kobo eReader over the reader's own sync protocol, so books arrive over wifi instead of over a USB cable.
+
+Answers [audiobookshelf#3504](https://github.com/advplyr/audiobookshelf/issues/3504), where people have been asking for Kobo sync for ebooks.
+
+**Not affiliated with Audiobookshelf, and not affiliated with Rakuten Kobo Inc.** This is an independent project. "Kobo" is a trademark of its owner and is used here only to say which device the software talks to.
+
+## What it does
+
+Your Audiobookshelf server already holds your epubs. Your eReader already knows how to sync a library over the network. kobobridge sits between the two and answers the sync protocol on behalf of your own server:
+
+```
+  Kobo eReader  ->  kobobridge  ->  Audiobookshelf
+                    (read only)
+```
+
+- New epubs in Audiobookshelf appear on the reader after a sync.
+- Covers, authors, series and descriptions come across.
+- Reading progress from the reader is stored by the bridge.
+- Large libraries are sent in batches, so the first sync completes.
+
+## What it does not do
+
+Worth reading before you install.
+
+- **It never writes to your library.** Every call to Audiobookshelf is a GET. Reading progress the reader pushes is kept in a small file next to the bridge, not pushed into Audiobookshelf, so progress does not yet show up in the Audiobookshelf web player. A test asserts this.
+- **It does not touch any account on the manufacturer's store.** No store credential, no user key, no device id. The bridge issues its own token and never contacts the store.
+- **It does not convert anything.** Only epub and kepub files are offered. Pdf, mobi and azw3 in your library are skipped rather than converted.
+- **Audiobooks and podcasts are skipped.** The reader cannot play them.
+- **Shelves and collections are not mirrored yet.**
+- **No telemetry, no phoning home, no analytics.** Nothing about your library leaves your machine.
+
+## Setup
+
+### 1. Get an Audiobookshelf API token
+
+In Audiobookshelf: Settings, Users, pick your user, then copy the API token.
+
+### 2. Run the bridge
+
+```
+export KOBOBRIDGE_ABS_URL=http://192.168.1.10:13378
+export KOBOBRIDGE_ABS_TOKEN=paste-your-token-here
+kobobridge check
+```
+
+The `check` command lists the ebooks the reader will be offered. If that looks right:
+
+```
+kobobridge run
+```
+
+It prints the one line you need to copy.
+
+### 3. Point the reader at the bridge
+
+```
+Point the eReader at this bridge:
+
+  1. Plug the eReader into a computer over USB.
+  2. Open the hidden folder .kobo/Kobo/ and edit 'Kobo eReader.conf'.
+  3. Under [OneStoreServices], set the line below. Create that
+     section if it is not already there.
+
+       api_endpoint=http://192.168.1.10:8484/kobo/rG9x2K7pQm4vB1nT8sYw
+
+  4. Eject, then sync from the eReader.
+```
+
+Keep a copy of the original `api_endpoint` value. Putting it back returns the reader to normal.
+
+To keep the same token across restarts, set `KOBOBRIDGE_DEVICE_TOKEN` to the value the bridge printed. Otherwise a new one is generated each run and the reader has to be pointed again.
+
+## Docker
+
+```
+docker run -d --name kobobridge -p 8484:8484 \
+  -e KOBOBRIDGE_ABS_URL=http://192.168.1.10:13378 \
+  -e KOBOBRIDGE_ABS_TOKEN=paste-your-token-here \
+  -e KOBOBRIDGE_DEVICE_TOKEN=pick-a-long-random-string \
+  -v kobobridge-data:/data \
+  ghcr.io/rezarys/kobobridge:latest
+```
+
+## Settings
+
+Required:
+
+- `KOBOBRIDGE_ABS_URL`: address of your Audiobookshelf server.
+- `KOBOBRIDGE_ABS_TOKEN`: Audiobookshelf API token.
+
+Optional:
+
+- `KOBOBRIDGE_DEVICE_TOKEN`: pin the reader token instead of generating one per run.
+- `KOBOBRIDGE_PUBLIC_URL`: the address the reader sees, when behind a reverse proxy.
+- `KOBOBRIDGE_LIBRARY_ID`: sync one library instead of every book library.
+- `KOBOBRIDGE_PORT`: port to bind, default 8484.
+- `KOBOBRIDGE_TIMEOUT`: seconds to wait on Audiobookshelf, default 30.
+
+## Security
+
+The reader token is the only thing standing between the internet and your library, so:
+
+- Keep the bridge on your home network, or behind a VPN such as Tailscale or Wireguard.
+- If you do expose it, put it behind a reverse proxy with TLS and set `KOBOBRIDGE_PUBLIC_URL`. The reader sends the token in the URL, which means it lands in access logs.
+- Pin `KOBOBRIDGE_DEVICE_TOKEN` to something long and random.
+
+## Status
+
+Version 0.1.0, first release. The shapes of the sync protocol were learned by reading the long standing [Calibre-Web](https://github.com/janeczku/calibre-web) implementation, which has served this protocol since 2019. Reading only: Calibre-Web is under the GPL, this project is under the MIT licence, and no code was copied from it. The Audiobookshelf side and the batching logic are covered by tests.
+
+What has not been exercised yet is a full sync against a physical reader, because the author does not own one. If you try it, an issue saying what happened is the single most useful thing you can send, working or not.
+
+## Development
+
+```
+git clone https://github.com/Rezarys/kobobridge
+cd kobobridge
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. Younes Z.

kobobridge-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kobobridge"
+version = "0.1.0"
+description = "Serve an Audiobookshelf ebook library to a Kobo eReader over the native sync protocol."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Younes Z." }]
+requires-python = ">=3.9"
+keywords = [
+  "kobo",
+  "audiobookshelf",
+  "ebook",
+  "epub",
+  "selfhosted",
+  "sync",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Web Environment",
+  "Framework :: Flask",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+]
+dependencies = [
+  "flask>=2.2",
+  "requests>=2.28",
+  "waitress>=2.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+kobobridge = "kobobridge.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/Rezarys/kobobridge"
+Source = "https://github.com/Rezarys/kobobridge"
+Issues = "https://github.com/Rezarys/kobobridge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kobobridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kobobridge-0.1.0/src/kobobridge/__init__.py

@@ -0,0 +1,12 @@
+"""Serve an Audiobookshelf ebook library to a Kobo eReader over the native sync protocol."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "create_app"]
+
+
+def create_app(config=None):
+    """Build the WSGI application. Imported lazily to keep ``import kobobridge`` cheap."""
+    from .app import create_app as _create_app
+
+    return _create_app(config)

kobobridge-0.1.0/src/kobobridge/__main__.py

@@ -0,0 +1,133 @@
+"""The command line: check the connection, print the setup line, run the server."""
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .abs import AudiobookshelfError
+from .config import Config, ConfigError
+
+
+def _load_config():
+    try:
+        return Config.from_env()
+    except ConfigError as error:
+        sys.stderr.write("kobobridge: {0}\n".format(error))
+        raise SystemExit(2)
+
+
+def _endpoint(config, host, port):
+    if config.public_url:
+        return "{0}/kobo/{1}".format(config.public_url, config.device_token)
+    shown = "127.0.0.1" if host in ("0.0.0.0", "::", "") else host
+    return "http://{0}:{1}/kobo/{2}".format(shown, port, config.device_token)
+
+
+def _print_setup(config, host, port):
+    endpoint = _endpoint(config, host, port)
+    print("")
+    print("Point the eReader at this bridge:")
+    print("")
+    print("  1. Plug the eReader into a computer over USB.")
+    print("  2. Open the hidden folder .kobo/Kobo/ and edit 'Kobo eReader.conf'.")
+    print("  3. Under [OneStoreServices], set:")
+    print("")
+    print("       api_endpoint={0}".format(endpoint))
+    print("")
+    print("  4. Eject, then sync from the eReader.")
+    print("")
+    if not os.environ.get("KOBOBRIDGE_DEVICE_TOKEN"):
+        print("This token was generated for this run only. To keep it across restarts, set:")
+        print("")
+        print("  KOBOBRIDGE_DEVICE_TOKEN={0}".format(config.device_token))
+        print("")
+
+
+def cmd_check(args):
+    config = _load_config()
+    from .app import Bridge
+
+    bridge = Bridge(config)
+    try:
+        count = bridge.client.ping()
+    except AudiobookshelfError as error:
+        sys.stderr.write("kobobridge: {0}\n".format(error))
+        return 1
+    print("Audiobookshelf answered: {0} librar{1}.".format(count, "y" if count == 1 else "ies"))
+    try:
+        books = bridge.refresh(force=True)
+    except AudiobookshelfError as error:
+        sys.stderr.write("kobobridge: {0}\n".format(error))
+        return 1
+    print("Ebooks the eReader can read: {0}.".format(len(books)))
+    for book in books[: args.limit]:
+        author = ", ".join(book.authors) or "unknown author"
+        print("  {0} ({1}) [{2}]".format(book.title, author, book.ebook_format))
+    if len(books) > args.limit:
+        print("  and {0} more.".format(len(books) - args.limit))
+    if not books:
+        print("")
+        print("No epub found. Audiobookshelf only reports one when the library item has an")
+        print("ebook file; audiobooks and podcasts are skipped on purpose.")
+    return 0
+
+
+def cmd_setup(args):
+    config = _load_config()
+    _print_setup(config, args.host, args.port)
+    return 0
+
+
+def cmd_run(args):
+    config = _load_config()
+    from .app import create_app
+    from waitress import serve
+
+    app = create_app(config)
+    _print_setup(config, args.host, args.port)
+    print("Listening on {0}:{1}. Stop with Ctrl+C.".format(args.host, args.port))
+    serve(app, host=args.host, port=args.port, threads=args.threads)
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="kobobridge",
+        description="Serve an Audiobookshelf ebook library to a Kobo eReader.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command")
+
+    def with_address(sub):
+        sub.add_argument("--host", default="0.0.0.0", help="address to bind, default 0.0.0.0")
+        sub.add_argument(
+            "--port", type=int, default=int(os.environ.get("KOBOBRIDGE_PORT", 8484)),
+            help="port to bind, default 8484",
+        )
+        return sub
+
+    run = with_address(subparsers.add_parser("run", help="run the bridge"))
+    run.add_argument("--threads", type=int, default=8, help="worker threads, default 8")
+    run.set_defaults(func=cmd_run)
+
+    check = subparsers.add_parser("check", help="test the Audiobookshelf connection")
+    check.add_argument("--limit", type=int, default=10, help="how many titles to list")
+    check.set_defaults(func=cmd_check)
+
+    setup = with_address(subparsers.add_parser("setup", help="print the eReader setup line"))
+    setup.set_defaults(func=cmd_setup)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())