Check a book file or a video before you publish it. Each gate is one rule set with a cited source, a PASS/WARN/FAIL verdict, JSON output and an exit code, so a person, a CI job or an AI agent can stop a bad upload before the platform does.
$ gatepack check kdp-metadata book.json
FAIL kdp-metadata book.json
FAIL working-note: subtitle still contains a working note: "TODO"
WARN trademark: title mentions "Minecraft" (the example trademark list); KDP disallows unauthorized references to trademarked terms [platform-rule]
FAIL contact-info: description contains a URL, e-mail address or phone number [platform-rule]
result: FAIL (2 fail, 1 warn)
rule sources:
- KDP: Metadata Guidelines for Books: https://kdp.amazon.com/en_US/help/topic/G201097560
Contributions welcome. One gate = one pull request: a rule, its source, a PASS file and a FAIL file. 15 gates are waiting for an owner.
pip install "gatepack[cover]" # Python 3.10+; installs pypdf, and Pillow for the cover gate
gatepack list # what can be checked
gatepack check loudness clip.mp4 # needs ffmpeg on PATH for audio/video gatesBefore the first PyPI release, install from the repository:
pip install "gatepack[cover] @ git+https://github.com/Essa366/gatepack".
Exit codes: 0 PASS or WARN, 1 FAIL (or WARN with --strict), 2 the gate could not run.
Add --json for machine-readable output.
| Gate | Checks | Rule source |
|---|---|---|
kdp-metadata |
title length, trademarks, sales-rank claims, contact details, review requests, coloring/puzzle books listed as eBooks, trim size and counts that contradict the book, leftover TODOs | KDP Metadata Guidelines, Keywords, Kindle Content Quality |
kdp-cover-safezone |
cover size, artwork in the trim, wrap and hinge zones, spine text rules | Paperback cover, Hardcover cover |
kdp-pagecount |
page count limits, page size vs trim and bleed, pages promised in the listing | Print Options, Trim, Bleed, Margins |
epub |
mimetype, container, required metadata, missing files, broken XHTML, author name; runs EPUBCheck if installed | EPUB 3.3, EPUBCheck |
dead-air |
long silences, silent start, silent file | heuristic, measured with silencedetect |
freeze |
picture that stops changing | heuristic, measured with freezedetect |
loudness |
integrated LUFS and true peak for streaming, podcast or broadcast | Spotify, Apple Podcasts, EBU R 128 |
tail |
ending cut off mid-sound, audio longer or shorter than the picture | heuristic |
Every finding says where it comes from: platform-rule (a platform's help page), standard
(a published standard), or heuristic (a threshold we chose and document, which you can change).
# Kindle eBook metadata, with your own list of trademarks to avoid
gatepack check kdp-metadata book.json --brands my-brands.txt
# Paperback interior: page limits and 6 x 9 trim with or without bleed
gatepack check kdp-pagecount interior.pdf --trim 6x9 --metadata book.json
# Full wrap cover (PNG/JPEG, or PDF with PyMuPDF installed)
gatepack check kdp-cover-safezone cover.png --trim 6x9 --pages 120
gatepack check kdp-cover-safezone cover.pdf --format hardcover --trim 6x9 --spine 0.6
# Podcast episode against Apple's -16 LUFS, as JSON for a CI step
gatepack check loudness episode.mp3 --profile podcast --json
# Every short in a folder, blocking on warnings too
gatepack check dead-air renders/*.mp4 --strictFrom Python:
import gatepack
result = gatepack.check("tail", "short.mp4")
print(result.status, [f.message for f in result.findings])The repository is also a Claude Code plugin with a gatepack skill that tells the agent which gate to
run before it reports a file as ready to upload:
/plugin marketplace add Essa366/gatepack
/plugin install gatepack@gatepack
The skill is in skills/gatepack/SKILL.md. Other agents can read the same file.
- It does not guarantee that KDP, a podcast host or a video platform will accept your file. Human reviewers apply rules no tool can see.
- It never logs in, uploads, scrapes or publishes anything. gatepack makes no network calls, and it runs ffmpeg with a file-only protocol whitelist so a playlist cannot pull in URLs.
- It is not a trademark database. The built-in list is a short example; bring your own.
git clone https://github.com/Essa366/gatepack && cd gatepack
pip install -e ".[dev]"
gatepack new youtube-thumbnail --category image # writes the module, docs page and fixture foldersFill in the rule and its source, add one file that must PASS and one that must FAIL, run pytest.
The full walk-through is in docs/adding-a-gate.md, the rules for pull
requests in CONTRIBUTING.md.
Written with Claude Code. The KDP rules come from book uploads that were rejected or flagged, and each one is checked against the platform page linked above. If a rule here disagrees with the platform's current page, the page wins: please open an issue.