book-sync

Tandem은 정식 릴리스 전 단계(0.1.0, 태그된 릴리스 없음)의 셀프 호스팅 프로젝트로, 책을 읽고 같은 책을 들으면서 읽던 위치를 절대 잃어버리지 않는 것을 목표로 합니다. 서버는 PostgreSQL 및 웹 앱과 함께 Docker에서 실행되며, React PWA와 Kotlin/Jetpack Compose 기반의 Android 앱이 씬 클라이언트로 작동합니다. 서버는 모든 상태 관리 작업을 수행합니다. 전자책과 오디오북 볼륨을 스캔하고, 메타데이터와 표지를 추출하며, 전자책과 오디오북을 쌍으로 묶고, 전사 큐를 실행하며, 동기화 맵을 생성하고, 읽기 위치를 기록하는 유일한 주체가 됩니다. 클라이언트는 JWT 인증이 적용된 REST 엔드포인트를 통해 위치를 읽고 쓰며, 기기 로컬 캐시만 유지합니다. 차별화된 기능은 포맷 간의 문장 단위 핸드오프입니다. 읽기에서 듣기로(또는 그 반대로) 전환하면 장의 시작 부분이 아니라 기기에 관계없이 읽고 있던 바로 그 문장에서 시작합니다. 이를 위해서는 전사본이 필요합니다. 오디오북을 전사하여 EPUB 텍스트와 정렬하는 방식입니다. Whisper는 선택적 로컬 스택으로 빌드된 서버 이미지에서 로컬로 실행하거나, 기본적으로 별도의 Jetson 워커(faster-whisper; Orin Nano 8GB가 참조 배포 모델이며 기본적으로 medium 모델 사용)로 작업을 전달할 수 있습니다. 재시도 기능, 업무 외 시간 설정, 전사본 편집기가 포함된 전사 큐가 함께 제공됩니다. 전사는 선택 사항이며, 전사가 없어도 라이브러리와 두 가지 리더를 사용할 수 있지만 포맷 간 동기화는 불가능합니다. 그 외 설명된 기능으로는 시리즈 그룹화 및 전자책/오디오북 자동 페어링이 포함된 라이브러리 스캐너, 잠금 화면 컨트롤이 포함된 PWA 웹 리더/플레이어(iOS 앱이 없으므로 iPhone용), 오프라인 다운로드, 백그라운드 재생 및 Android Auto를 지원하는 Android 리더/리스너, 역할 기반의 다중 사용자 계정과 기본 초대 전용 등록, 선택적 통합(Audiobookshelf, Google Books, Open Library 메타데이터, 특수 이미지 빌드가 필요한 ACSM/Audible 가져오기), 그리고 UI에서 복구 가능한 야간 Postgres 덤프 및 표지 스냅샷 등이 있습니다. 배포는 Docker Compose를 통해 이루어집니다. README에는 비밀 정보(JWT 키, Postgres 비밀번호, secrets/ 하위의 Fernet 자격 증명 암호화 키)를 환경 변수가 아닌 파일에 저장해야 한다는 점, 큐와 스케줄러가 프로세스 로컬이므로 서버가 단일 프로세스로 실행되어야 한다는 점, 그리고 신규 설치 시 로그에 기록된 무작위 비밀번호를 가진 superadmin이 생성되어 첫 로그인 시 비밀번호 재설정이 강제된다는 점이 매우 명시적으로 설명되어 있습니다. 리버스 프록시 설정에는 FORWARDED_ALLOW_IPS 설정이 필요하며, 강화된 Caddyfile 예시가 제공됩니다. 광범위한 환경 변수 표를 통해 필수, 선택, 인증 스로틀링, 업로드 제한 및 동기화 조정 설정을 다루며, API 문서(/docs, /redoc)는 운영 환경에서 의도적으로 비활성화됩니다. 문서화된 제한 사항은 솔직하게 기술되어 있습니다. 동기화는 EPUB만 가능(PDF는 페어링은 되지만 정렬은 불가, MOBI/AZW3는 변환 필요), 오디오북은 단일 파일이어야 함(다중 파일 립은 건너뛰므로 .m4b로 먼저 병합 필요), 한 번에 하나의 전사만 가능, 수평 확장 불가, iOS 앱 없음, Android Auto 하드웨어 테스트 미완료, 크래시 리포팅 기능 없음, 최근에 추가된 다운로드/스트리밍 경로, 그리고 앱 스토어에 등록되지 않은 점 등입니다. 이 프로젝트는 실제 테스트 스위트를 갖추고 일상적으로 사용 중인 1인 유지관리자의 노력으로 설명되며, 작성자의 환경 외의 하드웨어 및 라이브러리 레이아웃에 대한 노출은 제한적입니다.