DEV Community

Stanley Chege Thuita
Stanley Chege Thuita

Posted on Edited on

Away from the keyboard: Kisumu Market Day

The short version: Most of my posts are about code. This one is about a day away from it, at Kisumu Market Day, and then, because I can't help it, about the code that turned my phone clips from that day into a 30-second video: a script, not an editing app. How the cuts are chosen, how captions are timed to a synthetic voice, how visitors' faces are kept out by an assertion that fails the build, and how loudness is measured to the decimal. Every number comes from the real export.

Most of my posts here are about code: the Bitcoin Lightning wallet I build from Kisumu, Kenya, and what I learn reviewing Bitcoin's code.

On 13 November I stepped away from the keyboard for Kisumu Market Day at Baraza Media Lab: two days of the city's creators, makers and storytellers under one roof, opening with a photo exhibition about Lake Victoria.

Watch the 30-second walk-through on TikTok

Contents

  1. Why a developer goes to a market day
  2. What I saw
  3. Editing with a script instead of an app
  4. The edit is data
  5. Rule one: no visitor's face, enforced by an assertion
  6. A voice, and captions timed to it
  7. Sound: muting what can't be understood
  8. Frames: from phone clips to 1080 by 1920
  9. The upload copy: two-pass encoding to a size
  10. Captions in the safe zone
  11. Measuring the result
  12. Counting cuts: what "a cut" means to a machine
  13. What a market day teaches a developer

Why a developer goes to a market day

The people building things here are the people my tools are for. kTown, the QR code that lets Kisumu shops take bitcoin and receive M-Pesa, only works if real shop owners, makers and creators understand it and want it. Meeting them in person teaches me more about what they need than any issue tracker.

A developer's blind spot is assuming users think like developers. Makers and small sellers choose how to get paid based on trust, convenience and what their customers already use. That's why kTown pays out in M-Pesa rather than asking anyone to hold bitcoin, and why I'd rather meet people at their stalls than guess.

What I saw

The exhibition, "Between The Lake", was photographs of Lake Victoria and the life around it: a picnic with an unexpected guest, rocks older than all of us, the city after dark, and the golden hour every Kisumu kid knows. Around it, Kisumu's makers, designers and storytellers, under one roof at Lake Basin Mall.

It ran Friday and Saturday, 13 and 14 November, 8:30am to 7pm. Not sponsored: I went to meet Kisumu's builders.

Editing with a script instead of an app

The walk-through on TikTok wasn't cut in an editing app. It was built by a Python script that turns three raw files (the event flyer, a selfie clip at the venue, and a walk through the photo exhibition) into a finished vertical video, then hands the motion graphics to Remotion, a framework that renders React components as video frames.

Why a script for a 30-second clip?

  • Reproducible. Change one caption, re-run, get the same video with one difference. No "which version did I export?".
  • Reviewable. The edit is a text file I can read top to bottom, like code.
  • Rules can be enforced. Like "no visitor's face appears", as an assertion (below) instead of a promise.
  • Consistent. Every video I post uses the same voice, caption style and loudness target, because they're code, not settings I remember to click.

The pipeline:

raw clips + flyer
   │
   ├─ 1. the edit as data      blocks of (spoken line, caption chunks, shots, on-screen label)
   ├─ 2. voice                 a text-to-speech voice reads each line → WAV per line
   ├─ 3. timeline              shot lengths and caption timings derived from the voice durations
   ├─ 4. frames                OpenCV + ffmpeg build the 1080×1920 base video
   ├─ 5. sound                 ambient audio cleaned and levelled; unclear speech muted
   ├─ 6. graphics              Remotion renders captions, labels and the "ticket" card on top
   └─ 7. finish                loudness normalised; a small upload copy encoded
Enter fullscreen mode Exit fullscreen mode

The edit is data

The whole video is a list of blocks. Each block says what is spoken, how the caption is split into on-screen chunks (with *asterisks* marking the word highlighted in yellow), which shots play under it, and whether a gallery-style label appears. Simplified:

BLOCKS = [
    ("First stop, a photo exhibition, all about the lake.",
     ["First stop,", "a photo *exhibition*,", "all about the *lake*."],
     [("exhibition.mp4", 0.0)],                    # (clip, start second)
     ("Between The Lake", "photo exhibition")),    # wall label
    ...
]
Enter fullscreen mode Exit fullscreen mode

Everything else is derived. That's the main design decision: the voice decides the timing. A block lasts as long as its spoken line takes to say, plus small fixed gaps. Shots under a block share its duration in proportion to weights. So rewriting a line automatically re-times every shot and caption after it, which is exactly what makes a hand-edited timeline painful.

Rule one: no visitor's face, enforced by an assertion

People at the exhibition hadn't agreed to be in a video. So certain time ranges of the exhibition clip, where visitors' faces are visible, are listed as off-limits, and after the timeline is computed, every shot is checked against them. A minimal version of the idea:

NO_USE = [("exhibition.mp4", 6.2, 7.4), ("exhibition.mp4", 10.5, 13.2), ("exhibition.mp4", 41.8, 99)]

for clip, start, length in shots:
    for bad_clip, a, b in NO_USE:
        if clip == bad_clip:
            assert start + length <= a or start >= b, ("excluded range used", clip, start, length)
Enter fullscreen mode Exit fullscreen mode

If a later edit stretches a shot into a forbidden range (say, a caption gets longer and the shot under it grows), the build fails instead of quietly publishing someone's face. It's the same principle as a test in software: a rule that matters is enforced by the machine, not by remembering it.

A voice, and captions timed to it

The narration is a synthetic voice made with Kokoro, an open text-to-speech model that runs locally. My videos use one consistent voice, a blend of two of its built-in voices (55% and 45%) read slightly faster than default (1.08×). Each line becomes its own WAV file, trimmed to the first and last sample above a small threshold, with a few milliseconds of padding, so there's no dead air between lines.

Captions need word timing, and a synthetic voice doesn't come with subtitles. The approach is simple: each caption chunk gets a share of its line's duration proportional to its length in characters:

duration = length_of(line_wav)
total = sum(len(chunk.replace("*", "")) for chunk in chunks)
t = line_start
for chunk in chunks:
    end = t + duration * len(chunk.replace("*", "")) / total
    captions.append((chunk, t, end))
    t = end
Enter fullscreen mode Exit fullscreen mode

It's not phoneme-accurate, but at 1 to 4 words per chunk, the error is a fraction of a second and the eye doesn't notice. Every third caption also triggers a small "punch-in" zoom, a cheap pattern interrupt that keeps short-form video from feeling static.

The last spoken block always includes "Not sponsored", spoken and captioned. That's a standing rule for every video I publish, enforced the same way the rest is: it's in the script.

Sound: muting what can't be understood

The selfie clip at the venue had my voice, but the hall was loud and the speech wasn't intelligible enough to caption accurately. Rather than publish words people couldn't make out (or captions I'd have to guess), that clip is used muted, and the narration carries the story.

The exhibition clip's ambient sound is kept, quietly, for atmosphere. Each piece is:

  1. high-pass filtered at 60 Hz (removes rumble and handling noise),
  2. levelled to the same quiet target, about −38 dBFS RMS, so cuts don't jump in volume,
  3. faded in and out over 30 ms, so cuts don't click.

The fade is the kind of detail that's invisible when right and very audible when wrong: an audio cut at a non-zero sample is a click.

Frames: from phone clips to 1080 by 1920

The base video is built frame by frame. For each shot, ffmpeg decodes the clip from its start time, resamples it to 30 fps, and pipes raw RGB frames to Python, which scales them to 1080 × 1920 and pipes them into a second ffmpeg process that encodes H.264. No intermediate files per shot: frames stream from one process to the other.

The flyer, a still image, gets the treatment every still needs in video: a blurred, darkened copy of itself fills the background, and the sharp flyer sits on top with a slow push-in (7% zoom over the shot), so a still frame doesn't look frozen.

A light sharpen and a small contrast and saturation lift are applied in the final encode, once, so every shot gets the same treatment.

The upload copy: two-pass encoding to a size

The master is encoded for quality (59.9 MB); the copy I upload is encoded to a size. Uploads from Kisumu go over mobile data, and some platforms cap file size, so the target is "under about 7 MB" rather than "as good as possible".

Hitting a file size means choosing a bitrate. Size is bitrate times duration, so for a 6.5 MB target over 32.5 seconds with 128 kbit/s of audio:

video bitrate = 6.5 MB × 8000 kbit/MB ÷ 32.5 s − 128 kbit/s ≈ 1472 kbit/s
Enter fullscreen mode Exit fullscreen mode

A single pass at a fixed bitrate wastes bits on easy frames and starves hard ones. Two-pass encoding fixes that: the first pass only analyses the video and writes a log of how complex each part is; the second pass spends the same total bits where they're needed.

ffmpeg -i master.mp4 -c:v libx264 -preset medium -b:v 1472k -pass 1 -an -f null /dev/null
ffmpeg -i master.mp4 -c:v libx264 -preset medium -b:v 1472k -pass 2 \
       -c:a aac -b:a 128k -movflags +faststart upload.mp4
Enter fullscreen mode Exit fullscreen mode

I re-ran this on the real master for this post:

6615869 bytes                      (target 6.5 MB, landed at 6.6 MB)
duration=32.500000  bit_rate=1628521
I: -14.1 LUFS                      (loudness unchanged)
SSIM All: 0.947424 (12.792113)     (compared with the 59.9 MB master)
Enter fullscreen mode Exit fullscreen mode

SSIM compares the two videos' structure frame by frame: 1.0 is identical, and around 0.95 means differences you'd struggle to see on a phone at normal viewing distance. A 9× smaller file for a barely visible difference is the right trade for an upload. -movflags +faststart moves the file's index to the front, so playback can start before the whole file has downloaded, which matters most on a slow connection.

Captions in the safe zone

A vertical video on TikTok, Reels or Shorts isn't fully visible: the platform draws its own buttons on top. The rules my pipeline follows for every video:

Area Covered by Rule
Top ~220 px Search, "Following / For You" tabs No captions or labels
Bottom ~420 px Caption text, username, music, progress bar No captions or labels
Right ~140 px Like, comment, share buttons Keep text clear of it

So captions sit in a box around the middle-lower third, the hook text near the middle, and gallery labels in the upper-middle band. Because these are constants in the Remotion composition, not choices made per video, no caption ever ends up under the like button.

Measuring the result

"It looks fine on my phone" isn't a measurement, so every export is checked with ffprobe and ffmpeg. The real numbers for this video:

ffprobe -v error -show_entries format=duration,size,bit_rate:stream=codec_name,width,height,r_frame_rate,sample_rate -of compact market-day.mp4
ffmpeg -i market-day.mp4 -af ebur128 -f null - 2>&1 | grep -A12 Summary
Enter fullscreen mode Exit fullscreen mode
== master
stream|codec_name=h264|width=1080|height=1920|r_frame_rate=30/1|
stream|codec_name=aac|sample_rate=48000
format|duration=32.500000|size=59922483|bit_rate=14750149
    I:         -14.1 LUFS
    LRA:         1.3 LU
== upload copy
format|duration=32.500000|size=6686237|bit_rate=1645842
    I:         -14.1 LUFS
    LRA:         1.3 LU
Enter fullscreen mode Exit fullscreen mode

What those lines mean:

  • −14.1 LUFS integrated loudness. Platforms like YouTube, TikTok and Instagram normalise audio to around −14 LUFS. Delivering at that level means the platform doesn't turn the video down (or up, adding noise). Hitting −14.1 comes from a normalisation pass in the pipeline, checked afterwards with this measurement.
  • 1.3 LU loudness range. Very consistent: no sudden loud moments. That's the narration-led mix doing its job.
  • 59.9 MB down to 6.7 MB for the upload copy, a 9× reduction at about 1.6 Mbit/s, the same length and loudness. Upload limits and slow mobile connections in Kisumu both reward the small file.
  • About 18 scene changes at a 0.3 threshold, but see the next section: that number counts zooms too. The real hard cuts are fewer.

Counting cuts: what "a cut" means to a machine

I quoted "about 18 cuts" above, and that number deserves suspicion, because it depends entirely on a threshold. ffmpeg's select filter can score how different each frame is from the one before (0 means identical, 1 means completely different), and showinfo prints the frames that pass:

ffmpeg -i market-day.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null - 2>&1 | grep -c pts_time
Enter fullscreen mode Exit fullscreen mode

Run at four thresholds on the same video:

threshold 0.2: 22
threshold 0.3: 18
threshold 0.4: 6
threshold 0.5: 5
Enter fullscreen mode Exit fullscreen mode

From 22 "cuts" down to 5, same file. At 0.4, the detected moments are:

pts_time:2.53  7.20  10.50  19.73  26.33  29.40
Enter fullscreen mode Exit fullscreen mode

Those six line up with real changes of source: flyer to selfie, selfie to exhibition, between exhibition sections, and back to the flyer for the event details. The lower thresholds also count the slow push-in zooms, the caption punch-ins and fast camera pans inside a single shot, which change many pixels without being edits.

So the honest description of this video is: about 6 hard cuts between sources in 32.5 seconds (a new source roughly every 5 seconds), with continuous movement inside each shot (zooms, punch-ins every third caption, and the camera walking the exhibition) keeping the frame changing every second or two. That distinction matters when you study other creators' videos to learn their pacing: always say which threshold you used, or the number means nothing.

What a market day teaches a developer

  1. Users aren't developers. Trust, convenience and the money people already use matter more than any feature list.
  2. Show, don't explain. At the stalls, a working example beats a pitch. That's why every kTown shop sees me pay first, with my own sats, before anything else.
  3. Rules belong in code. Whether it's "no visitor's face" in a video or "an activist's own all-clear never ends an alarm" in Kengele, a rule you care about should fail a build when broken.

If you're in Kisumu, say hi next time. And if you build tools for creators and small businesses in East Africa, I'd like to hear what you've learned from your users.

Not sponsored.

Top comments (0)