00jlich/abs-kosync-bridge

ABS-KoSync 桥接工具

镜像概述和主要用途

ABS-KoSync Bridge是连接听觉与视觉的缺失环节，能够在Audiobookshelf（有声书平台）和KOReader/KoSync（电子书平台）之间无缝同步阅读进度。用户可在车内开始收听有声书，然后在Kindle或Kobo设备上从完全相同的位置继续阅读电子书。

核心功能和特性

• 无缝进度同步：自动同步Audiobookshelf有声书与KOReader/KoSync电子书的阅读进度
• 跨设备接续：支持在不同设备间切换阅读，保持进度一致
• 防循环机制：通过设置阈值忽略因四舍五入误差导致的微小进度变化
• 智能匹配：基于模糊匹配算法关联有声书与电子书
• 灵活配置：可自定义同步周期、匹配阈值等参数

使用场景和适用范围

• 经常在多种设备间切换阅读的用户
• 同时使用有声书和电子书形式阅读同一内容的读者
• 需要在通勤（有声书）和静读（电子书）场景间无缝切换的用户

部署指南

Docker Compose配置示例

yaml
services:
  # ---------------------------------------------------------------------------
  # 1. 桥接服务
  # ---------------------------------------------------------------------------
  abs-kosync:
    image: docker.xuanyuan.run/00jlich/abs-kosync-bridge:latest
    container_name: abs_kosync
    restart: unless-stopped
    # depends_on:
    #  - audiobookshelf
    #  - kosync
    
    # 重要：机器学习库需要共享内存
    shm_size: '2gb'

    environment:
      - TZ=America/New_York
      # --- 服务器连接 ---
      - ABS_SERVER=http://audiobookshelf:80
      - ABS_KEY=your_abs_api_key_here
      - KOSYNC_SERVER=http://kosync:3000
      - KOSYNC_USER=admin
      - KOSYNC_KEY=your_kosync_password
      
      # --- 同步逻辑 ---
      - SYNC_PERIOD_MINS=5
      # 防循环：忽略因四舍五入误差导致的微小变化
      - SYNC_DELTA_ABS_SECONDS=60
      - SYNC_DELTA_KOSYNC_PERCENT=1
      
      # --- 匹配逻辑 ---
      - FUZZY_MATCH_THRESHOLD=80
      - KOSYNC_HASH_METHOD=content  # 使用'content'获取KOReader原生哈希

    volumes:
      # 尽可能映射与KOReader设备相同的文件夹结构，
      # 或仅映射包含EPUB文件的根文件夹
      - ./library:/books
      - ./bridge_data:/data

配置变量说明

使用指南

1. 匹配向导

同步前，必须将有声书与电子书关联：

bash
docker-compose run --rm abs-kosync python src/main.py match

1.1. 从列表中选择有声书
1.2. 从列表中选择电子书
1.3. 完成。任务已排队，可关闭终端。容器日志将显示转录进度

2. 监控

查看日志以监控同步过程：

bash
docker-compose logs -f abs-kosync

• 处理中：显示下载和转录状态
• 同步中：显示正在匹配的文本及计算的XPath路径