Skip to content
Essa366Public

About

Check-before-you-publish gates for KDP books and short videos: cited rules, PASS/WARN/FAIL, JSON, CLI and Claude Code plugin

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

gatepack

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.

Quick start

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 gates

Before 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.

Gates

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).

Examples

# 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 --strict

From Python:

import gatepack

result = gatepack.check("tail", "short.mp4")
print(result.status, [f.message for f in result.findings])

Use it from Claude Code

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.

What it does not do

  • 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.

Add a gate

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 folders

Fill 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.

How it was built

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.

License

MIT

About

Check-before-you-publish gates for KDP books and short videos: cited rules, PASS/WARN/FAIL, JSON, CLI and Claude Code plugin

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages