General: Keep the previously-focused app out of the declaration video

record.sh started the screen capture and then launched Amply, so the
first ~2.5s of every take showed whatever app was previously in the
foreground during the launch animation. In the current take that was
Octi, listing the owner's devices and sync server. Launch and settle
before the capture starts instead.

postprocess.sh gains TRIM_START (or a trim.txt) to salvage an existing
take by dropping N seconds off the front, shifting caption timings to
match; this take renders with 2.5s trimmed. The trim happens inside the
filtergraph with an explicit timestamp reset — input seeking on
screenrecord's variable-rate output made the fps filter pad the cut back
out with ~60 duplicate frames, which silently lengthened the title card.

The render now lands next to its DECLARATION.md and is git-ignored, so
it can be kept on disk ready to upload without entering the repository.

Author: d4rken

.gitignore

@@ -9,4 +9,8 @@ captures/
 .kotlin/
 # Ephemeral screenshot-test reference renders (regenerated by fastlane/generate_screenshots.sh)
 app/src/screenshotTest*/reference/
+# Rendered declaration screencasts (regenerated by fastlane/play-declarations/*/record.sh).
+# Kept on disk for upload to the Play Console, never committed — they are large and
+# they capture whatever was on the recording device's screen.
+fastlane/play-declarations/**/*.mp4
 

fastlane/play-declarations/README.md

@@ -26,8 +26,10 @@ unlisted YouTube video or a link-shared Google Drive file.
 
 The video is regenerated on a device with no manual screen recording: the recorder drives Amply
 with label-based taps (robust to layout changes) while `screenrecord` captures, then post-processing
-adds a title card, burned-in captions, and an end card. **The scripts are committed; the `.mp4`
-output is not** — it is written to `/tmp/amply-demo/` and regenerating it is one command.
+adds a title card, burned-in captions, and an end card. **The scripts are committed; the `.mp4` is
+not** — `.gitignore` excludes `fastlane/play-declarations/**/*.mp4`, so the render can live next to
+its `DECLARATION.md` (ready to upload) without ever entering the repository. Intermediate artifacts
+(`raw.mp4`, `captions.txt`, the card text) stay in `/tmp/amply-demo/`.
 
 | File | Role |
 |------|------|
@@ -40,11 +42,19 @@ output is not** — it is written to `/tmp/amply-demo/` and regenerating it is o
 # Requires a PHYSICAL, capability-gated device (an emulator fails the gate and
 # would record the diagnostics-only UI). Default serial is the Pixel 7a.
 ./foreground-service-special-use/record.sh 31071JEHN17531
-./postprocess.sh /tmp/amply-demo/foreground-service-special-use
+./postprocess.sh /tmp/amply-demo/foreground-service-special-use \
+                 foreground-service-special-use/declaration.mp4
 
 # NOREC=1 ./foreground-service-special-use/record.sh   # validate the tap chain, no recording
+# TRIM_START=2.5 ./postprocess.sh …                    # drop N seconds off the front
 ```
 
+`TRIM_START` (or a `trim.txt` in the output dir) exists to salvage a take whose opening frames
+caught something they shouldn't have; caption timings are shifted to match. It should not normally
+be needed — `record.sh` launches Amply and lets it settle *before* the capture starts, because
+launching inside the recording puts the previously-focused app on screen for the duration of the
+launch animation.
+
 ### What the recorder guarantees
 
 - **It refuses a bad take.** It aborts if the device does not start at the 80% limit (the restore

fastlane/play-declarations/foreground-service-special-use/DECLARATION.md

@@ -95,7 +95,8 @@ promptly, and interrupting it causes user-visible harm) but matches no defined t
 ## 6. Demo video
 
 Produced by `./record.sh` (see [`../README.md`](../README.md)). Recorded on a physical Pixel 7a,
-portrait 720×1600, ~68 s including title and end cards.
+portrait 720×1600, ~64 s including title and end cards. The rendered file sits next to this
+document as `declaration.mp4` and is git-ignored — upload it, don't commit it.
 
 The video demonstrates the **unplug** stop condition rather than the 100% one. That is deliberate:
 it is the condition that cannot work without a running foreground service, because Android does not

fastlane/play-declarations/foreground-service-special-use/record.sh

@@ -59,12 +59,15 @@ if ! have "Charge to 100% once"; then
   echo "         adb -s $SERIAL shell pm grant $PKG android.permission.WRITE_SECURE_SETTINGS" >&2
   exit 1
 fi
-# Restart into a clean dashboard so the recording opens on a settled screen.
+# Restart into a clean dashboard and let it settle BEFORE the capture starts.
+# Launching inside the recording would put the previously-focused app on screen
+# for the ~2.5s of the launch animation — whatever the user happened to have open.
 app_stop; pause 1
+app_launch; pause 4
 
 # ---- recording --------------------------------------------------------------
 rec_start
-app_launch; pause 4
+pause 2.5
 cap "Plugged in — the battery is held\nat the 80% protection limit"
 pause 3.5
 

fastlane/play-declarations/postprocess.sh

@@ -1,13 +1,20 @@
 #!/usr/bin/env bash
 # Assemble a declaration video from a recorder's output dir:
-#   <OUTDIR>/raw.mp4 + captions.txt + title.txt + end.txt  ->  <OUTDIR>/declaration.mp4
+#   <OUTDIR>/raw.mp4 + captions.txt + title.txt + end.txt  ->  <OUTFILE>
 #
-# Usage: ./postprocess.sh [OUTDIR]
+# Usage: ./postprocess.sh [OUTDIR] [OUTFILE]
+#
+# Trimming: seconds to drop from the START of raw.mp4, read from <OUTDIR>/trim.txt
+# or $TRIM_START (default 0). Caption timings are shifted to match. This salvages a
+# take whose opening frames caught the previously-focused app during the launch
+# animation; record.sh now launches the app before recording starts, so a fresh
+# take should not need it.
 set -euo pipefail
 
 OUTDIR="${1:-/tmp/amply-demo/foreground-service-special-use}"
-RAW="$OUTDIR/raw.mp4"; CAPS="$OUTDIR/captions.txt"; OUT="$OUTDIR/declaration.mp4"
+RAW="$OUTDIR/raw.mp4"; CAPS="$OUTDIR/captions.txt"; OUT="${2:-$OUTDIR/declaration.mp4}"
 TITLE="$OUTDIR/title.txt"; END="$OUTDIR/end.txt"
+TRIM_START="${TRIM_START:-$( [ -f "$OUTDIR/trim.txt" ] && cat "$OUTDIR/trim.txt" || echo 0 )}"
 
 FONT=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf
 FONTB=/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf
@@ -18,16 +25,24 @@ W=720; H=1600; FPS=30; BG=0x00332B      # Amply brand dark teal
 [ -f "$END" ]   || printf 'Protection is restored\nautomatically.' > "$END"
 TXTDIR="$(mktemp -d)"; trap 'rm -rf "$TXTDIR"' EXIT
 
-dur=$(ffprobe -v error -select_streams v:0 -show_entries format=duration -of csv=p=0 "$RAW")
+raw_dur=$(ffprobe -v error -select_streams v:0 -show_entries format=duration -of csv=p=0 "$RAW")
+dur=$(awk -v d="$raw_dur" -v t="$TRIM_START" 'BEGIN{printf "%.3f", d-t}')
+[ "$(awk -v d="$dur" 'BEGIN{print (d>1)?1:0}')" = 1 ] || { echo "TRIM_START=$TRIM_START leaves nothing of $RAW"; exit 1; }
+[ "$TRIM_START" = "0" ] || echo "Trimming ${TRIM_START}s from the start of raw.mp4"
 
 # --- timed-caption drawtext chain from captions.txt --------------------------
+# Caption timestamps are relative to the untrimmed raw, so shift them by TRIM_START
+# and drop any caption whose window closes before the new start.
 chain=""
 if [ -f "$CAPS" ]; then
   mapfile -t lines < "$CAPS"
   n=${#lines[@]}
   for ((i=0;i<n;i++)); do
     start=${lines[i]%%|*}; text=${lines[i]#*|}
-    if (( i+1 < n )); then end=${lines[i+1]%%|*}; else end=$dur; fi
+    if (( i+1 < n )); then end=${lines[i+1]%%|*}; else end=$raw_dur; fi
+    start=$(awk -v v="$start" -v t="$TRIM_START" 'BEGIN{v-=t; printf "%.2f", (v<0)?0:v}')
+    end=$(awk -v v="$end" -v t="$TRIM_START" 'BEGIN{printf "%.2f", v-t}')
+    awk -v s="$start" -v e="$end" 'BEGIN{exit !(e>0 && e>s)}' || continue
     printf '%b' "$text" > "$TXTDIR/c$i.txt"   # %b expands a literal \n into a line break
     chain+=",drawtext=expansion=none:fontfile=${FONT}:textfile=${TXTDIR}/c$i.txt:fontcolor=white:fontsize=27:line_spacing=10:box=1:boxcolor=0x000000C0:boxborderw=16:x=(w-text_w)/2:y=h-190:enable='between(t,${start},${end})'"
   done
@@ -39,7 +54,7 @@ ffmpeg -y -loglevel error -stats \
   -f lavfi -i "color=c=${BG}:s=${W}x${H}:d=4:r=${FPS}" \
   -filter_complex "
     [0:v]format=yuv420p,drawtext=expansion=none:fontfile=${FONTB}:textfile=${TITLE}:fontcolor=white:fontsize=32:line_spacing=18:x=(w-text_w)/2:y=(h-text_h)/2[t];
-    [1:v]fps=${FPS},scale=${W}:${H},setsar=1,format=yuv420p${chain}[m];
+    [1:v]trim=start=${TRIM_START},setpts=PTS-STARTPTS,fps=${FPS},scale=${W}:${H},setsar=1,format=yuv420p${chain}[m];
     [2:v]format=yuv420p,drawtext=expansion=none:fontfile=${FONTB}:textfile=${END}:fontcolor=white:fontsize=36:line_spacing=18:x=(w-text_w)/2:y=(h-text_h)/2[e];
     [t][m][e]concat=n=3:v=1:a=0[v]
   " -map "[v]" -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p -movflags +faststart "$OUT"