Energy report

The HTML video

us-power-mix.html is the single-file export, playing right here. Click it, then press ? for the keys, or open it on its own.

Video: final.mp4 · 1920x1080 · 30 fps · 60.10 s · 19.2 MB · -14.0 LUFS / -1.3 dBTP · Web page: us-power-mix.html (1.7 MB, one file, plays offline, 7 chapters)

The request#

"Make a one-minute narrated video from the EIA's electricity generation data showing how the US power mix changed: coal, gas, wind and solar."

Mode: quick, publish-bound (so a researcher pass before the final and a critic pass on it). No questions asked. The opening line stated the assumptions:

Quick mode: 60 s, 16:9, narrated (am_michael), news-bumper bed ducked under the voice, bold look. Data: EIA Monthly Energy Review (August 2026), Table 7.2a, annual, all sectors, frozen on 2026-09-27. Takeaway: coal made about half of US power for decades; gas passed it in 2016; in 2024 wind + solar passed it for the first time (672 vs 652 TWh), and again in 2025 (760 vs 737).

Contract: coal made about half of US electricity for decades; since its 2007 peak, gas took the lead in 2016, and in 2024 wind and solar together passed coal for the first time, all in EIA's own annual numbers.

The story, and where each number comes from#

Every figure is computed from data/eia-mer-T07.02A-2026-09-27.csv (EIA's CSV as downloaded, unchanged) by data/derive.py, and re-derived by crew/research/verify_claims.py (25 claims, all verified, in crew/research/claims.verified.json). Values are million kWh ÷ 1,000 = TWh, annual rows (YYYY13).

Definition checks the researcher settled before the build (research notes, not shipped):

• Table 7.2a "Solar" is utility-scale only. With small-scale solar (Table 10.6) added, 2023 is still below coal and 2024 above it, so "first time in 2024" holds either way; the numbers are labelled utility-scale.
• Before 1989 the table covers electric utilities only (except hydro), so the coal-era note says so and the narration says "about half" (coal's share ran 44.0-56.9 % in 1949-2008), never an exact long-run share.
• The narration says wind and solar, never "renewables" (this table's renewables include hydro and wood).
• In the race, wind and solar are separate, so neither bar passes coal; the subtitle says "wind and solar shown separately". Its bars carry no value labels: at 0.25 s a year every paused frame would show interpolated figures that are not in the table.

Commands, in order#

showtime is skills/showtime/bin/showtime; <job> is showtime-out/us-power-mix-20260927-114128, <p> is <job>/project.

showtime doctor --quick
showtime job init us-power-mix --mode quick --platform youtube --goal "Make a one-minute narrated video ..." \
  --assumed "Data: EIA MER (August 2026) Table 7.2a, frozen snapshot 2026-09-27; annual 1949-2025; solar utility-scale" \
  --assumed "Takeaway: ... gas passed coal in 2016; wind + solar passed coal in 2024 (672 vs 652)" \
  --assumed "60 s, 16:9, am_michael, news-bumper bed ducked under speech, bold theme"
showtime data inspect data/eia-mer-T07.02A-2026-09-27.csv      # long table: MSN, YYYYMM, Value
python3 data/derive.py                                          # -> annual TWh (wide), race table, 2025 shares
showtime data inspect data/us-generation-annual-twh.csv
showtime new data <p> --title "Wind and solar passed coal in 2024" --duration 60

# voice first: the narration sets the scene lengths
showtime voice script <p>/narration.md -o <p>/voice --fit 58   # 66.6 s natural: "cut about 23 words" -> cut
showtime voice script <p>/narration.md -o <p>/voice --fit 58   # 58.00 s at x1.0 (pauses -0.39 s)
showtime retime <p> --from-voice <p>/voice/timeline.json       # 7 scenes, 60.10 s; 7 voice tracks placed, bed ducks

# charts from the tables (the numbers never live in HTML)
showtime data import data/us-generation-annual-twh.csv <p> --chart line --x year --y coal,natural_gas,wind_solar \
  --decimals 0 --suffix " TWh" -o <p>/data/lines-1949-2025.json
showtime data import data/us-generation-race-2005-2025.csv <p> --chart race --x year --top 6 --step 0.25 \
  --decimals 0 --suffix " TWh" --highlight "Natural gas" --scene race -o <p>/data/race-2005-2025.json \
  --title "Six sources, ranked by generation" --subtitle "TWh per year · wind and solar shown separately"
showtime data import data/us-mix-2025-shares.csv <p> --chart hbar --x source --y share_pct --top 6 --decimals 1 \
  --suffix " %" --highlight Coal --annotate "Coal: +13 % in 2025" --ref "15.1:Coal in 2024: 15.1 %" \
  --scene mix-2025 -o <p>/data/mix-2025.json --title "US electricity by source, 2025" --subtitle "Share of 4,430 TWh"
#   (race state titles "... · 2005" replaced by a "year" field: a title per 0.25 s state flickers; see Tool issues found)
for i in flame atom wind sun droplet pickaxe ellipsis; do showtime assets icon lucide $i --stroke 2 -o <p>/icons/$i.svg; done
showtime assets icon lucide wind --color "#3ddc97" -o <p>/icons/wind-g.svg     # (and sun-g, pickaxe-c for the hook cards)

# first look, fix, look again (6 rounds of stills while building)
showtime snap <p> --at 0,1,3,7.6,9.5,12.5,...,59.5 --width 960 --format jpg --sheet
showtime check <p>        # custom components not mounted (registered after auto-mount) -> mounted from a module script
showtime check <p>        # 17 contrast errors (half-faded ticks, dimmed row names, the year pill over the ticks) -> fixed
showtime check <p>        # PASS, 5 warnings (read: decade labels leaving the frame during the scene-4 zoom)
showtime render <p> --job <job> --preview                       # 720p draft, 1 m 05 s
showtime snap <job>/preview.mp4 --at 14.7,15.0,15.3,...         # the morph-warp and the two soft cuts
showtime audio meter <job>/preview.mp4                          # -14.0 LUFS, LRA 2.5
python3 crew/research/verify_claims.py data/us-generation-annual-twh.csv crew/research/claims.verified.json   # 25/25

# final, verify, review, fix
showtime render <p> --job <job>          # final.mp4
showtime qa <job>                        # FAIL: must_show "Table 7.2a", "August 2026" not found (check keeps 80 chars
                                         #   of a text) -> the source line split in two; black 0.7 s at the last cut
showtime render <p> --job <job>          # final-2.mp4
showtime qa <job>                        # WARN: black 0.4 s after the last crossfade
showtime review-pack <job>               # round 1 -> self-review (below)
showtime render <p> --from 53.3 --to 53.7 --workers 1 -o <job>/work/cut-test.mp4   # reproduces an empty frame at 53.433
showtime render <p> --from 53.3 --to 54.3 --workers 1 -o <job>/work/cut-test2.mp4  # fixed
showtime render <p> --job <job>          # final-3.mp4 -> qa WARN (black 0.4 s)
showtime check <p>; showtime render <p> --job <job>              # final-4.mp4
showtime qa <job>                        # PASS (0 fail, 0 warn, 0 note)
showtime review-pack <job>               # round 2 -> self-review of the fixes

# deliver
showtime deliver exports <job> --targets youtube,x,linkedin,github
showtime deliver exports <job> --targets original --max-mb 20   # this folder's final.mp4
showtime qa <job>/exports/final-4.20mb.mp4 --project <p> --platform youtube   # PASS
showtime deliver poster <job>/final-4.mp4 --at 7.6 --out <job>/poster-final4.jpg
showtime export html <p> --target artifact --subtitle "Where US electricity came from, 1950-2025 · U.S. EIA data" -o <job>/us-power-mix.html
showtime clean <job> -y                  # freed 303.9 MB (frames, scratch, audio intermediates)

# round 3: an independent critic pass on the published file (see Review), fixes, one full-res render
showtime snap <p> --at 0,7.6,14.5,...,54.3 --width 960 --format jpg --sheet    # each finding, before changing anything
showtime snap <p> --at 33.1,33.3,...,39.1 --width 640 --sheet --cols 6          # the race, every 0.2 s: readout vs bar order
showtime check <p>                       # PASS, 11 warnings (axis year labels during the two x-axis moves, read)
showtime render <p> --job <job>          # final-5 .. final-8: qa WARN each (a 2.5 s still in scene 3 or 4 after
                                         #   re-balancing the camera push; 0.27-0.43 s of near-black at the last crossfade)
showtime render <p> --from 53.0 --to 55.0 --workers 1 -o <job>/work/cut-test3.mp4   # tune the end card's entry
showtime render <p> --job <job>          # final-9.mp4
showtime qa <job>                        # PASS (0 fail, 0 warn, 0 note)
showtime snap <job>/final-9.mp4 --at 0,7.6,15.13,15.37,30.1,30.6,33.5,...,53.97 --compare <job>/final-4.mp4
showtime job discard <job> final-5.mp4   # (and final-6, final-7, final-8)
showtime deliver exports <job>/final-9.mp4 --targets original --max-mb 20      # this folder's final.mp4
showtime qa <job>/exports/final-9.20mb.mp4 --project <p> --platform youtube   # PASS (0 warn)
showtime deliver exports <job>/final-9.mp4 --targets youtube,x,linkedin,github
showtime deliver poster <job>/final-9.mp4 --at 7.6 --out <job>/poster-final9.jpg
showtime export html <p> --target artifact ...                                # re-exported

Exports made from final-9 (not all committed): youtube 16.7 MB, x 12.6 MB, linkedin 12.6 MB, github 9.5 MB (10 MB cap), original under 20 MB 19.2 MB (this final.mp4); all 1920x1080, -14.1 LUFS, -1.2 to -1.3 dBTP.

Features shown#

About the crew. This session had no sub-agent tool, so the director did each crew task from its brief (references/crew/*.md) and wrote the same files a crew member would: the storyboard (crew/storyboard/storyboard.md), the two motion-designer tasks (crew/motion-*/TASK.md, built into power.js), the researcher's check (crew/research/) and the critic's findings (review/). The critic rounds are therefore labelled self-reviews; a second look by a person is the remaining step.

Review#

Round 1 (on final-2.mp4, self-review): ship after fixes.

Round 2 (on final-4.mp4, fixes only): ship. Every fix confirmed on the cut frames; qa PASS with 0 warnings.

Round 3 (an independent critic on the published final.mp4 = final-4, from the round-2 pack plus its own frames): ship after fixes. The numbers, caveats and credit all checked out. Fixed in final-9.mp4; each fix was confirmed on a still of the new render at the cited time, next to the same time in final-4.

Side effects handled: the camera push in scenes 2-4 was re-balanced so the cut stays seamless (scene 2 now 0.976 -> 0.99, scene 3 0.99 -> 1.012, scene 4 1.012 -> 1.03 as before) without a still of 2.5 s or more and without pushing the y-axis labels to the frame edge (both seen and fixed in the unused renders final-5 to final-8).

QA summary#

showtime qa on the published file (final.mp4 = the job's final-9 re-encoded under 20 MB): PASS (0 fail, 0 warn, 0 note). The master final-9.mp4 (31.2 MB): PASS, 0 warn, -14.0 LUFS / -1.5 dBTP.

• h264 High, yuv420p, 1920x1080, 30 fps, faststart, BT.709; 60.10 s, matching showtime.json
• loudness -14.0 LUFS, true peak -1.3 dBTP (master: -14.0 / -1.5); no silent gaps; no black or frozen stretches
• frame 0 has a picture and flows into frame 1 (the kicker, headline and footnote; the cards rise in and the numbers count up from 0.35 s, so poster.jpg is the settled hook at 7.6 s and is not baked into frame 0)
• must_show: 672, 652, 2024, 2,016, 2007, 48.5, 2016, 760, 737, 40.8, 17.7, 17.2, 16.6, Table 7.2a, August 2026 all found
• no attribution required (no CC-BY items)

showtime check: PASS with 11 warnings, all x-axis year labels that leave while the axis moves (the 2007 -> 2025 stretch at 15 s and the 1995-2025 zoom at 22.5 s), read and kept; deterministic; fonts embedded (Bricolage Grotesque, Inter, JetBrains Mono); contrast OK for all text.

Tool issues found (reported, worked around here)#

• A race's per-state titles crossfade from 0 on every state, so at --step under ~0.4 s the title flickers; the year is shown by year-tick instead.
• The hbar chart ignores valueLabels: false; the race hides them with CSS.
• check records at most 80 characters per text, so a must_show phrase late in a long line is "not found".
• A CSS crossfade whose data-start sits within 1 ms after a frame boundary rendered one empty frame in render (not in snap).
• A race from data import --chart race --step 0.25 trails its states by about a second in the stock hbar (each state morphs after 0.35 s over 0.8 s, so the tweens overlap), and near-equal rows share a slot while the soft rank settles; a year readout timed to the states is then a year ahead. row-kit's race mode works around it here.
• data import --y wind_solar names the series "Wind solar" (the "+" is lost); the component maps it back.

Timings#

Shared 6-core Intel i5 with other example builds running.

Files#

final.mp4              the video (qa PASS), 19.2 MB
poster.jpg             the settled hook at 7.6 s (cover image)
us-power-mix.html      the same video as one offline web page (export html --target artifact)
share.txt              YouTube/X/LinkedIn copy with chapters, alt text, posting notes
credits.txt            data, icons, fonts, voice, music
data/                  EIA CSV as downloaded, derive.py, the three derived tables
project/               index.html, power.js, showtime.json, narration.md, audio/mix.json, data/*.json, icons/, voice/ (timings)
crew/                  storyboard, motion-designer tasks, researcher script + claims.verified.json
review/                round 1 and round 2 findings (self-reviews); round 3 is in this README

To rebuild: the voice WAVs are not committed; run showtime voice script project/narration.md -o project/voice --fit 58, then showtime render project.

Sources and licences#

• Data: U.S. Energy Information Administration, Monthly Energy Review (August 2026, released 2026-08-26), Table 7.2a "Electricity Net Generation: Total (All Sectors)", https://www.eia.gov/totalenergy/data/browser/index.php?tbl=T07.02A, CSV https://www.eia.gov/totalenergy/data/browser/csv.php?tbl=T07.02A, accessed 2026-09-27. EIA: "U.S. government publications are in the public domain and are not subject to copyright protection" (https://www.eia.gov/about/copyrights_reuse.php); the acknowledgment with the publication date is on screen and in share.txt. The EIA logo is a registered trademark and is not used. The next edition (2026-09-29) may revise the 2025 values; re-derive with data/derive.py before reusing.
• Icons: Lucide (ISC), via showtime assets icon; license sidecars next to each file.
• Fonts: Bricolage Grotesque, Inter, JetBrains Mono, SIL OFL 1.1, served locally by showtime.
• Voice: Kokoro-82M (Apache-2.0), voice am_michael, synthesized on this machine.
• Music and effects: composed and synthesized locally (news-bumper, key D, seed 3; thock, whoosh, ding). No samples or library tracks.

The project files on GitHub