Goodnotes PDF Engine 0.2

Goodnotes 앱을 자동 조작하지 않고 .goodnotes ZIP 내부의 protobuf 인덱스를 읽어 현재 페이지 순서와 원본 PDF·이미지 배경을 재구성하는 Python CLI입니다.

A cautious, app-independent Python CLI that reconstructs PDF backgrounds and experimentally renders pen strokes from .goodnotes archives.

현재 지원 범위

• Goodnotes 6/7 계열 아카이브의 index.events.pb, index.notes.pb, index.attachments.pb 직접 해석
• 삭제된 페이지를 제외한 현재 페이지 순서 복원
• 여러 PDF 첨부 파일과 페이지 번호를 하나의 PDF로 재조립
• JPEG, PNG, TIFF 페이지와 빈 페이지 처리
• 경로 탈출, 비정상적으로 큰 ZIP, 깨진 protobuf, 잘못된 PDF 페이지 참조 방어
• JSON 변환 보고서 생성
• Apple LZ4와 TPL로 저장된 펜 필기 3개 포맷의 실험적 벡터 렌더링
• 폴더 일괄 변환

중요한 제한

기본값인 strict 모드는 현재 페이지의 notes/ 데이터가 하나라도 있으면 PDF를 만들지 않고 종료합니다. 따라서 데이터 손실을 정상 변환으로 오인하지 않습니다.

--annotations experimental은 펜·형광펜 계열의 세 가지 TPL 좌표 포맷을 벡터 선으로 렌더링합니다. 도형, 텍스트 상자, 스티커, 사진 등 다른 Goodnotes 오브젝트는 아직 완전 지원하지 않으며 보고서에 생략 개수가 기록됩니다. Goodnotes 자체 렌더러와 픽셀 단위로 동일하다고 보장하지 않습니다.

실험적 펜 렌더링은 Apple LZ4 해제를 위해 현재 macOS의 libcompression을 사용합니다. strict와 ignore의 배경 재구성 경로는 이 기능에 의존하지 않습니다.

배경만 필요한 경우에만 --annotations ignore를 명시하세요. 생성된 JSON 보고서에는 생략된 페이지 수와 바이트 수가 기록됩니다.

설치

Python 3.10 이상이 필요합니다. 실험적 펜 렌더링은 현재 macOS에서만 지원합니다.

git clone https://github.com/fakeminjun7321/goodnotes-pdf-engine.git
cd /path/to/goodnotes-pdf-engine
python3 -m venv .venv
.venv/bin/python -m pip install -e .

사용법

구조 확인:

goodnotes-pdf inspect "문서.goodnotes"

안전한 변환(필기 데이터가 있으면 중단):

goodnotes-pdf convert "문서.goodnotes" -o "문서.pdf"

펜 필기를 실험적으로 렌더링:

goodnotes-pdf convert "문서.goodnotes" -o "문서.pdf" --annotations experimental

필기를 생략하고 배경 PDF만 생성:

goodnotes-pdf convert "문서.goodnotes" -o "문서.pdf" --annotations ignore

기존 PDF나 보고서를 덮어써야 할 때만 --overwrite를 추가하세요. 기본값은 기존 파일 보호입니다.

폴더 일괄 처리:

goodnotes-pdf batch "입력 폴더" -o "출력 폴더" --recursive --annotations ignore

종료 코드는 성공 0, 일반 오류 2, strict 필기 안전 중단 3입니다. 배치 모드는 일부라도 실패하면 1입니다.

개발

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python -m build

버그 제보와 기여 방법은 CONTRIBUTING.md, 보안 문제 제보 방법은 SECURITY.md를 참고하세요.

라이선스 및 상표

코드는 MIT License로 배포됩니다.

이 프로젝트는 Goodnotes와 제휴하거나 Goodnotes가 보증한 제품이 아닙니다. Goodnotes 이름과 관련 상표는 각 권리자에게 속합니다. 파일 형식은 앱 버전에 따라 변경될 수 있으므로 중요한 원본은 별도로 보관하세요.