A local video studio for your coding agent. Describe a video in one sentence: your agent directs, your machine renders. Claude Code, Codex, Cursor, Devin and more. No API keys, no uploads.
The showtime site
A companion site for the repository: a landing page with the hero film, a gallery that plays every
example, the crew, the documentation (rendered from skills/showtime/references/, with a sidebar and
search) and the interactive HTML videos. It is plain static files with relative links, built by one
Python script: no framework, no trackers, no cookies, no external requests (the fonts are served from
the site itself, under their OFL licenses in static/fonts/).
| Path | What it is |
|---|---|
build.py |
the build: Markdown to HTML (markdown-it-py), pages, search index, media copy |
config.json |
the one value to set: repo (owner/name); plus site_url (the published address), the version and the hero film (its folder, film, still, length and credit) |
content/crew.json |
the one-line job of each crew member, as the crew page shows it |
content/xray.json |
the X-ray page (xray/): its hero, the kinds, and the gallery's entries (title, object, mechanism, layout, theme, aspect, receipt, clip credit and license, commands, author). Each video and poster is looked up as examples/_xray/<file> (the examples checkout, or <dir>/_xray/<file> in a --media-from folder, or its release asset) and copied to media/xray/; a missing film shows its poster, a missing poster a plain card. An entry with no receipt shows as "In the works", with no player and no commands |
content/previews.json |
the 4-second window of each example the gallery previews on hover |
content/harness.html |
the body of "How showtime is built" (harness/): the crew's operating manual, in its own design (static/harness.css, scoped to .harness, and static/harness.js; its fonts are in static/fonts/ under the OFL). Its first line, <!-- ARTICLE_URL=... -->, is where section 14's "Favio on X" link goes. media/NAME in it is examples/_harness/NAME (loops, posters, the 0.4.3 film, the link-preview card) |
static/ |
style.css, app.js (theme, gallery filters and players, copy buttons, search), fonts |
tools/hero_loop.py |
cuts a seamless loop (dissolving its end into its start) from a film; it made the 0.2.0 hero teaser in examples/_launch/ |
tools/benchmark_pages.py |
the benchmark report pages at /benchmark/ (one per version, from release assets), with a bar that links the versions and the newest rounds' write-up (benchmarks/rounds/r5-allout.md) |
Build it locally
git clone https://github.com/FavioVazquez/showtime-examples ../showtime-examples # the examples, next to this clone
python3 -m pip install markdown-it-py # or use showtime's venv: ~/.showtime/venv/bin/python
python3 site/build.py --media-from ../showtime-examples/examples/ # writes site/_site/
python3 site/build.py --examples ../showtime-examples/examples --out /tmp/site --clean
Open site/_site/index.html in a browser (it works from disk) or serve the folder with
python3 -m http.server -d site/_site. The examples live in their own repository,
showtime-examples; the build reads them from
--examples DIR, else from a clone next to this one (examples_dir in config.json,
../showtime-examples/examples). --media-from says where the example videos are: that clone's
examples/ folder (the release assets are there if you downloaded them), or a folder of release assets
named as in its examples/MEDIA.json; repeat it to look in several. A video that
is not found is skipped: its card shows the preview loop and links to the release asset instead.
--repo owner/nameturns links to repository files into GitHub links and adds release links. Without it (and withconfig.jsonrepoempty) those links render as plain text.--only 05,20,22copies the full videos of those examples only: a small preview build.- The gallery previews each example on hover with a silent 4-second clip and a still, cut with ffmpeg from
the window in
content/previews.json(showtime's own ffmpeg,$SHOWTIME_FFMPEG, or one onPATH; cached insite/_cache/). Without ffmpeg, or with--no-previews, it uses the README loops instead. - Search:
search-index.jsholds each page whole, in sections (one per h2 and h3), so a hit opens its section. The index and the typed query share one rule (SEARCH_SEPARATORSinbuild.py,norm()inapp.js):` * _ > | # -become spaces, sopr-videofinds "pr video". The build fails if the index names a page twice, a page it did not write, or an anchor the page does not have. - Raw HTML in the Markdown is limited to the tags the docs use on purpose (
HTML_TAGSinbuild.py: pictures, centred paragraphs, the example tables,<kbd>,<details>and a few more). Any other tag, such as a<title>or<project>placeholder in prose, is shown as text. - Link previews: every page has
og:title, anog:descriptionof whole sentences (about 200 characters, never cut inside a sentence),og:urland a canonical link. The address comes fromsite_urlinconfig.json, else the GitHub Pages address ofrepo. The HTML videos copied undermedia/get the same tags, with their example's description and poster: the exports in the media release are older than the export's own share tags (sharein showtime.json,references/html-export.md). Tags an export wrote itself win where they can. sitemap.xml(every page and HTML video),robots.txt(allows everything and names the sitemap) andllms.txt(a short Markdown index for agents: what showtime is, how to install it, and every docs page with one sentence) are written at the site's root. On a project site such asfaviovazquez.github.io/showtime/, crawlers read only the host's own robots.txt, so give the sitemap's address to a search console directly.- Every build ends with a check: each page has one
<title>and a footer, and a page made from one Markdown file has as many h2 headings as that file. A failure names the page and the cause, and the build exits with an error. _site/and_media/are git-ignored.
Deploy to GitHub Pages
.github/workflows/pages.yml builds and deploys on every push to main that touches the site, the
docs or the art, on a repository_dispatch event named examples-updated (send one after changing
showtime-examples: gh api repos/FavioVazquez/showtime/dispatches -f event_type=examples-updated), and on
demand. It checks out showtime-examples into _examples/, downloads that repository's media release
(named in its examples/MEDIA.json; gh release download <tag> --pattern '*.mp4' --pattern '*.html')
into _media/, then runs python3 site/build.py --examples _examples/examples --media-from _media --repo $GITHUB_REPOSITORY. While showtime-examples is private, the workflow needs a secret
EXAMPLES_TOKEN with read access to it; once it is public, the default token is enough. A full build is about 580 MB, under the Pages limit of 1 GB.
Publish checklist
Do these once, in order, when the repository goes public.
- Repository.
site/config.jsonalready namesFavioVazquez/showtime(CI passes$GITHUB_REPOSITORY, which wins). The site is served athttps://faviovazquez.github.io/showtime/; Pages works while the repository is private on GitHub Pro, but a private repository's Pages site is still public to anyone with the link. - Media release. In showtime-examples, publish the example media as the release named in its
examples/MEDIA.json(python3 scripts/publish_media.py --upload). The release lives in the examples repository (itsreleaseentry names it), so the links inexamples/README.mdandREADME.mdalready point athttps://github.com/FavioVazquez/showtime-examples/releases/download/<that tag>/; if the tag changes, regenerate them (python3 scripts/publish_media.py --links). - Launch film.
python3 scripts/publish_media.py --upload(in showtime-examples) publishes the films inexamples/_launch/(16:9, 1:1, 9:16 and the HTML video),examples/_showreel/(the 0.3.0 showreel and its HTML video) andexamples/_showreel041/(the 0.4.1 showreel) with the rest of the media. The landing page loops the 0.4.1 showreel's silent teaser (examples/_showreel041/teaser-16x9.mp4and.webm, in git) over its still (teaser-16x9.jpg), and its one button, "Watch the film", playsshowreel-16x9.mp4with sound (downloaded from the release at deploy time);heroinconfig.jsonnames these files.gallery_filminconfig.jsoncan put a film above the gallery's tabs; it isnull(none), and the 0.2.0 launch film's files stay inexamples/_launch/. The crew film plays on the crew page (crew.html#film). Viewers who ask for reduced motion see the still only. Each film's music credit is under it and in the footer; the composer's terms mean the audio never ships as a separate file. - Turn on Pages. Settings > Pages > Build and deployment > Source: GitHub Actions. Then
Actions > pages > Run workflow (or push to
main). The site appears athttps://faviovazquez.github.io/showtime/. - Link the site.
README.md(navigation and Docs) anddocs/README.mdalready link to that address; check the links once the first deploy is green, and add it as the repository's website (the gear next to "About"). - Hero video in the README. Until this step, the README shows the film's poster
(
assets/readme/launch-poster.jpg: the wordmark, the promise, example 19's real request and a frame of its video, and a play label) linking to the release asset. The site's hero uses the same design without the play label (launch-poster-plain.jpg). GitHub plays an MP4 with sound in a README only when it is a user attachment:- On github.com, open
README.mdand click the pencil (Edit). - Find
<!-- HERO-VIDEO-URL -->near the top. Delete the whole<p align="center">...</p>paragraph right under it (the poster image and its link). Leave the caption paragraph below it alone. - With the cursor on the now-empty line, drag
launch-16x9.mp4from your computer into the editor (68 MB, under the 100 MB limit; it can take a minute). GitHub inserts a line likehttps://github.com/user-attachments/assets/1a2b3c.... - Make sure that URL is alone on its line, with an empty line before and after it (no brackets, no
<video>tag), and commit. The README now plays the film with sound; the caption keeps the music credit.
- On github.com, open
- Social preview. Settings > General > Social preview > Edit > Upload an image:
assets/brand/social/github-social-preview.png(1280x640: the wordmark, the tagline and frames of four examples). The site already uses it as itsog:image. - Check the film in Safari. Open the site on a Mac and an iPhone: the teaser should loop silently, and "Watch the film" should play the film with sound. (Chrome and the WebKit engine are checked automatically.)
- Benchmark. When the benchmark is published, fill the hidden
BENCHMARK SECTIONinREADME.md(instructions inside the comment) and add it to the navigation line.