Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
"""Tests for backend.services.face_track_helpers: pure camera /
speaker-switch decision helpers.
"""
import os
import sys
import unittest
ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
BACKEND_ROOT = os.path.join(ROOT, "backend")
if BACKEND_ROOT not in sys.path:
sys.path.insert(0, BACKEND_ROOT)
from services import face_track_helpers as fth
class UpdateTripodCameraTests(unittest.TestCase):
def test_no_target_clamps_within_frame(self):
# No target → camera sits at current_center but clamped
result = fth.update_tripod_camera(
current_center_x=500, target_center_x=None,
crop_w=600, video_width=1920, dt=0.1,
)
self.assertEqual(result, 500)
def test_clamps_below_half_crop(self):
# current 100 with crop_w=600 → min center = 300
result = fth.update_tripod_camera(
current_center_x=100, target_center_x=None,
crop_w=600, video_width=1920, dt=0.1,
)
self.assertEqual(result, 300)
def test_clamps_above_width_minus_half(self):
# video_width - half_crop = 1920 - 300 = 1620
result = fth.update_tripod_camera(
current_center_x=1800, target_center_x=None,
crop_w=600, video_width=1920, dt=0.1,
)
self.assertEqual(result, 1620)
def test_force_snap_jumps_to_target(self):
result = fth.update_tripod_camera(
current_center_x=500, target_center_x=1200,
crop_w=600, video_width=1920, dt=0.1, force_snap=True,
)
self.assertEqual(result, 1200)
def test_small_drift_inside_safe_zone_holds(self):
# diff = 50, safe_zone_radius = 600 * 0.22 = 132 → hold
result = fth.update_tripod_camera(
current_center_x=600, target_center_x=650,
crop_w=600, video_width=1920, dt=0.1,
)
self.assertEqual(result, 600)
def test_large_drift_moves_toward_target(self):
# diff = 400 → outside safe zone → move toward it
result = fth.update_tripod_camera(
current_center_x=500, target_center_x=900,
crop_w=600, video_width=1920, dt=0.1,
)
# Should have moved right but not snapped all the way
self.assertGreater(result, 500)
self.assertLess(result, 900)
def test_movement_is_bounded_by_speed(self):
# Very fast diff, small dt → step limited by max speed × dt
result = fth.update_tripod_camera(
current_center_x=500, target_center_x=1800, # huge diff → fast_speed
crop_w=600, video_width=1920, dt=0.1,
)
# fast_speed=360, dt=0.1 → max step 36 → 500 + 36 = 536
self.assertEqual(result, 536)
class ChooseCameraSpeakerTests(unittest.TestCase):
def test_no_transcript_speaker_holds(self):
self.assertEqual(
fth.choose_camera_speaker(
transcript_speaker=None,
transcript_duration=5.0,
active_speaker="A",
pending_speaker=None,
pending_count=0,
),
("A", None, 0, False),
)
def test_first_speaker_becomes_active(self):
self.assertEqual(
fth.choose_camera_speaker(
transcript_speaker="A",
transcript_duration=5.0,
active_speaker=None,
pending_speaker=None,
pending_count=0,
),
("A", None, 0, True),
)
def test_same_speaker_continues(self):
self.assertEqual(
fth.choose_camera_speaker(
transcript_speaker="A",
transcript_duration=5.0,
active_speaker="A",
pending_speaker="B",
pending_count=2,
),
("A", None, 0, False),
)
def test_brief_interjection_ignored(self):
# transcript_duration < min_turn_duration → hold
self.assertEqual(
fth.choose_camera_speaker(
transcript_speaker="B",
transcript_duration=1.0, # brief
active_speaker="A",
pending_speaker=None,
pending_count=0,
),
("A", None, 0, False),
)
def test_new_speaker_enters_pending(self):
cam, pending, count, switched = fth.choose_camera_speaker(
transcript_speaker="B",
transcript_duration=5.0,
active_speaker="A",
pending_speaker=None,
pending_count=0,
)
self.assertEqual(cam, "A")
self.assertEqual(pending, "B")
self.assertEqual(count, 1)
self.assertFalse(switched)
def test_pending_confirmed_after_confirmation_frames(self):
# Previous pending=B, count=2; with confirmation_frames=3 the
# third sighting commits the switch.
cam, pending, count, switched = fth.choose_camera_speaker(
transcript_speaker="B",
transcript_duration=5.0,
active_speaker="A",
pending_speaker="B",
pending_count=2,
confirmation_frames=3,
)
self.assertEqual(cam, "B")
self.assertEqual(pending, None)
self.assertTrue(switched)
def test_different_pending_resets_count(self):
# Pending was B=1, now transcript speaker is C → reset to C=1
cam, pending, count, switched = fth.choose_camera_speaker(
transcript_speaker="C",
transcript_duration=5.0,
active_speaker="A",
pending_speaker="B",
pending_count=1,
)
self.assertEqual(pending, "C")
self.assertEqual(count, 1)
self.assertFalse(switched)
class SafeDefaultCenterTests(unittest.TestCase):
def test_uses_first_speaker_anchor_when_available(self):
self.assertEqual(
fth.safe_default_center(
width=1920, crop_w=600,
face_map=None, has_any_split=False,
first_speaker="A",
speaker_anchor_x={"A": 800.0},
),
800.0,
)
def test_uses_largest_face_map_cluster(self):
face_map = {
"clusters": [
{"center_x": 400, "count": 10},
{"center_x": 1500, "count": 50}, # largest
],
}
self.assertEqual(
fth.safe_default_center(
width=1920, crop_w=600,
face_map=face_map, has_any_split=True,
first_speaker=None,
speaker_anchor_x={},
),
1500.0,
)
def test_non_split_returns_center(self):
self.assertEqual(
fth.safe_default_center(
width=1920, crop_w=600,
face_map=None, has_any_split=False,
first_speaker=None, speaker_anchor_x={},
),
960.0,
)
def test_split_with_no_map_returns_left_quarter(self):
# Safer than the seam at the exact center.
self.assertEqual(
fth.safe_default_center(
width=1920, crop_w=600,
face_map=None, has_any_split=True,
first_speaker=None, speaker_anchor_x={},
),
480.0,
)
class ClampAwayFromDeadZoneTests(unittest.TestCase):
def test_non_split_is_noop(self):
self.assertEqual(
fth.clamp_away_from_dead_zone(
crop_x=100, crop_w=600, width=1920,
face_map={"clusters": []}, has_any_split=False,
),
100,
)
def test_no_face_map_is_noop(self):
self.assertEqual(
fth.clamp_away_from_dead_zone(
crop_x=660, crop_w=600, width=1920,
face_map=None, has_any_split=True,
),
660,
)
def test_crop_far_from_seam_passes_through(self):
# crop_center = 100 + 300 = 400; mid_x = 960; distance = 560 > margin
face_map = {"clusters": [{"center_x": 400}, {"center_x": 1500}]}
self.assertEqual(
fth.clamp_away_from_dead_zone(
crop_x=100, crop_w=600, width=1920,
face_map=face_map, has_any_split=True,
),
100,
)
def test_crop_near_seam_snaps_to_nearest_cluster(self):
# crop_x=660 → crop_center=960 (exactly on seam); nearest cluster = 1500
face_map = {"clusters": [{"center_x": 400}, {"center_x": 1500}]}
snapped = fth.clamp_away_from_dead_zone(
crop_x=660, crop_w=600, width=1920,
face_map=face_map, has_any_split=True,
)
# Should have moved off the seam
self.assertNotEqual(snapped, 660)
# crop_x still keeps the crop window on-frame
self.assertLessEqual(snapped + 600, 1920)
self.assertGreaterEqual(snapped, 0)
def test_near_seam_with_no_clusters_returns_left_quarter(self):
face_map = {"clusters": []}
result = fth.clamp_away_from_dead_zone(
crop_x=660, crop_w=600, width=1920,
face_map=face_map, has_any_split=True,
)
# width // 4 - crop_w // 2 = 480 - 300 = 180
self.assertEqual(result, 180)
class UpgradeSpeakerMappingsTests(unittest.TestCase):
def test_clears_old_mappings(self):
original = {
"clusters": [{"center_x": 400}],
"speaker_mappings": {"A": 0, "B": 1},
}
result = fth.upgrade_speaker_mappings(original)
self.assertEqual(result["speaker_mappings"], {})
self.assertTrue(result["_mappings_v2"])
def test_preserves_clusters(self):
original = {
"clusters": [{"center_x": 400}, {"center_x": 1500}],
"speaker_mappings": {"A": 0},
}
result = fth.upgrade_speaker_mappings(original)
self.assertEqual(len(result["clusters"]), 2)
def test_does_not_mutate_input(self):
original = {
"clusters": [],
"speaker_mappings": {"A": 0},
}
fth.upgrade_speaker_mappings(original)
# Original should still have the old mapping
self.assertEqual(original["speaker_mappings"], {"A": 0})
class CropCenterKeepingFacesVisibleTests(unittest.TestCase):
CROP_W = 607 # 9:16 out of a 1920x1080 source
WIDTH = 1920
def _center(self, xs):
return fth.crop_center_keeping_faces_visible(xs, self.CROP_W, self.WIDTH)
def test_unimodal_run_lands_on_the_group(self):
xs = [940, 950, 960, 970, 980]
center = self._center(xs)
self.assertLess(abs(center - 960), 30)
def test_bimodal_run_picks_the_bigger_side_not_the_gap(self):
# A run that spans a layout change: four samples fullscreen at 960,
# two on a split-screen tile at 1500. The median is 1230, which on a
# 607-wide crop holds on the wall between them and shows no one.
xs = [960, 955, 965, 950, 1500, 1505]
center = self._center(xs)
self.assertGreaterEqual(
sum(1 for x in xs if abs(x - center) < self.CROP_W / 2), 4
)
self.assertLess(abs(center - 960), 60)
def test_never_returns_a_center_with_nobody_in_frame(self):
# The exact shape that rendered as a hold on empty wall: two tiles far
# apart, nothing between them.
xs = [480, 470, 490, 1440, 1450, 1430]
center = self._center(xs)
self.assertTrue(any(abs(x - center) < self.CROP_W / 2 for x in xs))
def test_clamps_into_the_frame(self):
center = self._center([20, 25, 30])
self.assertGreaterEqual(center - self.CROP_W / 2, 0)
def test_no_faces_falls_back_to_center(self):
self.assertEqual(self._center([]), self.WIDTH / 2)
class SeatsFromFramesTests(unittest.TestCase):
WIDTH = 1920
def test_two_tiles_are_two_seats(self):
frames = [[480, 1440]] * 20
self.assertEqual(fth.seats_from_frames(frames, self.WIDTH), (480, 1440))
def test_one_person_wandering_across_the_midline_is_one_seat(self):
# The bug this replaced: 40 solo frames, some left of centre and some
# right of it, were counted as two people and rendered as a cut
# between a face and a wall.
frames = [[900]] * 20 + [[1020]] * 20
self.assertIsNone(fth.seats_from_frames(frames, self.WIDTH))
def test_two_heads_sharing_one_camera_are_one_seat(self):
frames = [[900, 1050]] * 20
self.assertIsNone(fth.seats_from_frames(frames, self.WIDTH))
def test_a_few_false_positives_cannot_seat_a_second_person(self):
frames = [[960]] * 100 + [[300, 1600]] * 3
self.assertIsNone(fth.seats_from_frames(frames, self.WIDTH))
def test_mixed_layout_still_finds_both_seats(self):
# Riverside-style: sometimes both tiles, sometimes one fullscreen.
frames = ([[480, 1440]] * 15) + ([[960]] * 25)
self.assertEqual(fth.seats_from_frames(frames, self.WIDTH), (480, 1440))
def test_no_frame_ever_held_two_faces(self):
self.assertIsNone(fth.seats_from_frames([[960]] * 50, self.WIDTH))
class FollowWithinRunsTests(unittest.TestCase):
CROP = 1215
WIDTH = 3840
def _follow(self, runs, points):
return fth.follow_within_runs(runs, points, self.CROP, self.WIDTH)
def _at(self, keys, t):
return [x for kt, x in keys if kt <= t][-1]
def test_a_still_face_keeps_a_still_camera(self):
points = [(i * 0.1, 1900.0 + (i % 3) * 20, 640.0) for i in range(100)]
keys = self._follow([(0.0, 10.0, 1900.0)], points)
self.assertEqual({x for _, x in keys}, {1900.0})
def test_a_close_face_that_leans_is_followed_before_it_leaves_frame(self):
points = [(i * 0.1, 1930.0, 650.0) for i in range(140)]
points += [(14.0 + i * 0.1, 2300.0, 850.0) for i in range(50)]
keys = self._follow([(0.0, 19.0, 1930.0)], points)
half = self.CROP / 2
self.assertLessEqual(abs(self._at(keys, 15.0) - 2300.0) + 425, half)
def test_a_layout_change_is_a_cut_not_a_pan(self):
points = [(i * 0.1, 1950.0, 640.0) for i in range(330)]
points += [(33.0 + i * 0.1, 1000.0, 680.0) for i in range(15)]
keys = self._follow([(0.0, 33.0, 1950.0), (33.0, 34.5, 1000.0)], points)
self.assertEqual(self._at(keys, 32.999), 1950.0)
self.assertEqual(self._at(keys, 33.0), 1000.0)
def test_the_camera_never_leaves_the_source(self):
points = [(i * 0.1, 50.0, 400.0) for i in range(30)]
keys = self._follow([(0.0, 3.0, 50.0)], points)
self.assertTrue(all(x >= self.CROP / 2 for _, x in keys))
class ReExportTests(unittest.TestCase):
def test_video_processor_reexports_all_helpers(self):
from services import video_processor as vp
self.assertIs(vp._update_tripod_camera, fth.update_tripod_camera)
self.assertIs(vp._choose_camera_speaker, fth.choose_camera_speaker)
self.assertIs(vp._safe_default_center, fth.safe_default_center)
self.assertIs(vp._clamp_away_from_dead_zone, fth.clamp_away_from_dead_zone)
self.assertIs(vp._upgrade_speaker_mappings, fth.upgrade_speaker_mappings)
self.assertIs(
vp._crop_center_keeping_faces_visible,
fth.crop_center_keeping_faces_visible,
)
self.assertIs(vp._clip_layout_is_mixed, fth.clip_layout_is_mixed)
self.assertIs(vp._followed_face_cx_at, fth.followed_face_cx_at)
if __name__ == "__main__":
unittest.main()
class FollowedFaceCxAtTests(unittest.TestCase):
"""The crop validator must ask where the *followed speaker* is, not where
the biggest face is.
On the recording this was written for, the two speakers sit at very
different distances from their own cameras: 845px of face against 518px.
Taking the larger one made a correct crop onto the quieter speaker look
like a crop onto nobody, so the validator pulled every keyframe back onto
the same person and the camera stopped switching for a 29-second turn.
"""
def _split(self, duration=10.0, fps=10):
# Left speaker has the much larger face, as the real recording does.
return [
(i / fps, [
{"cx": 950, "fw": 845, "track_id": 0},
{"cx": 2880, "fw": 518, "track_id": 1},
])
for i in range(int(duration * fps) + 1)
]
def test_follows_the_smaller_face_when_it_is_the_speaker(self):
tracks = [(0.0, 10.0, "SPEAKER_R", 1, 2880.0)]
cx = fth.followed_face_cx_at(5.0, self._split(), tracks)
self.assertEqual(cx, 2880.0)
def test_follows_the_larger_face_when_it_is_the_speaker(self):
tracks = [(0.0, 10.0, "SPEAKER_L", 0, 950.0)]
cx = fth.followed_face_cx_at(5.0, self._split(), tracks)
self.assertEqual(cx, 950.0)
def test_picks_the_track_for_the_turn_that_covers_the_time(self):
tracks = [(0.0, 4.0, "SPEAKER_L", 0, 950.0), (4.0, 10.0, "SPEAKER_R", 1, 2880.0)]
self.assertEqual(fth.followed_face_cx_at(2.0, self._split(), tracks), 950.0)
self.assertEqual(fth.followed_face_cx_at(8.0, self._split(), tracks), 2880.0)
def test_falls_back_to_the_prominent_face_when_the_speaker_is_absent(self):
# Followed track 1 is never on screen; any face beats none.
detections = [(i / 10, [{"cx": 950, "fw": 845, "track_id": 0}]) for i in range(50)]
tracks = [(0.0, 5.0, "SPEAKER_R", 1, 2880.0)]
self.assertEqual(fth.followed_face_cx_at(2.0, detections, tracks), 950.0)
def test_uses_the_fallback_track_outside_every_turn(self):
tracks = [(0.0, 2.0, "SPEAKER_L", 0, 950.0)]
cx = fth.followed_face_cx_at(6.0, self._split(), tracks, fallback_track_id=1)
self.assertEqual(cx, 2880.0)
def test_no_detections_nearby_gives_nothing(self):
detections = [(0.0, [{"cx": 950, "fw": 845, "track_id": 0}])]
tracks = [(0.0, 10.0, "SPEAKER_L", 0, 950.0)]
self.assertIsNone(fth.followed_face_cx_at(9.0, detections, tracks))