File size: 33,019 Bytes
8562e9b
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
"""CPU-only, replayable multi-event speech interference policy.

SIR is defined for the *combined* third-party track, excluding silence with the
existing active-RMS convention. It is not an independently sampled event SIR.
The final scalar peak protection scales target and background together.
"""
from __future__ import annotations

import copy
from collections import defaultdict
from functools import lru_cache
import math
from pathlib import Path
import random
from typing import Any, Mapping, Sequence

import numpy as np

from scripts.data.hfd_third_party_common import (
    SAMPLE_RATE, STRIDE_SAMPLES, active_rms, audio_stats, gain_for_db, measured_db,
    quantize_pcm16, read_pcm16_wav, sha256_file, stable_u64,
)
from scripts.data.scan_hfd_third_party_loudness import read_background, target_track

POLICY = "multi_event_speech_v5"
CLASS_PERCENTAGES = (
    ("single_short", 15), ("multi_single", 25), ("multi_babble", 15),
    ("mixed_short", 31), ("continuous", 10), ("same_voice_aside", 4),
)
CLASS_WEIGHTS = tuple((name, percentage / 100.) for name, percentage in CLASS_PERCENTAGES)
MIN_ACTIVE_SAMPLES = 160
PEAK_LIMIT = .95


def quota_counts(n: int) -> dict[str, int]:
    """Hamilton quotas in pairs, preserving exact per-class 50/50 languages.

    Ties follow CLASS_WEIGHTS declaration order. An odd population cannot meet
    the language contract and is rejected instead of silently rounding it.
    """
    if not isinstance(n, int) or isinstance(n, bool) or n < 0 or n % 2:
        raise ValueError("Population must be a nonnegative even integer")
    pairs = n // 2
    # Integer percentage arithmetic avoids platform-dependent floating ties.
    percentages = [percentage for _, percentage in CLASS_PERCENTAGES]
    counts = [pairs * percentage // 100 for percentage in percentages]
    order = sorted(range(len(counts)), key=lambda i: (-(pairs * percentages[i] % 100), i))
    for i in order[:pairs - sum(counts)]:
        counts[i] += 1
    return {name: 2 * count for (name, _), count in zip(CLASS_PERCENTAGES, counts)}


def truncated_sir(rng: random.Random, mu: float = 2., sd: float = 3.,
                  lo: float = -4., hi: float = 8.) -> float:
    """Sample a normal by rejection, never by clipping tail values."""
    if not all(math.isfinite(x) for x in (mu, sd, lo, hi)) or sd <= 0 or lo >= hi:
        raise ValueError("Invalid truncated-normal parameters")
    for _ in range(100000):
        value = float(rng.gauss(mu, sd))
        if lo <= value <= hi:
            return value
    raise ValueError("Truncated-normal rejection sampler exhausted its safety bound")


def _positive_samples(total: int, length: int) -> None:
    if any(not isinstance(x, (int, np.integer)) or isinstance(x, bool) or x <= 0
           for x in (total, length)):
        raise ValueError("Session and source lengths must be positive integers")


def placement_uniform(N: int, L: int, rng: random.Random) -> dict[str, Any]:
    """Uniform start over every session sample; source length does not bias it."""
    _positive_samples(N, L)
    start = rng.randrange(int(N))
    natural_end = start + int(L)
    return {
        "start_sample": start, "end_sample": min(int(N), natural_end),
        "natural_end_sample": natural_end, "uncropped_sample_count": int(L),
        "right_truncated": natural_end > N, "event_truncated": natural_end > N,
        "crop_reason": "session_end" if natural_end > N else None,
        "placement": "uniform_session_right_crop",
        "placement_policy": "uniform_full_session_right_crop_v1",
        "uniform_start_max_sample": int(N) - 1,
    }


def placement_same_voice_aside(N: int, L: int, target_events: Sequence[dict],
                               anchor_turn_index: int, rng: random.Random) -> dict[str, Any]:
    """Sample uniformly from free starts after an anchor command.

    Length does not restrict start eligibility. A sentence may be cut by the
    session end *or* the next target command, avoiding same-voice self-overlap.
    Eligible intervals are half-open sample intervals, not speech intervals.
    """
    _positive_samples(N, L)
    targets = []
    anchors = []
    for index, event in enumerate(target_events):
        start, end = int(event["start_sample"]), int(event["end_sample"])
        if not 0 <= start < end <= N:
            raise ValueError("Target interval outside session")
        targets.append((start, end))
        if int(event.get("turn_index", index)) == anchor_turn_index:
            anchors.append(end)
    if len(anchors) != 1:
        raise ValueError("Aside anchor must identify exactly one target turn")
    cursor = anchors[0]
    eligible = []
    for start, end in sorted(targets):
        if end <= cursor:
            continue
        if start > cursor:
            eligible.append([cursor, start])
        cursor = max(cursor, end)
    if cursor < N:
        eligible.append([cursor, int(N)])
    population = sum(end - start for start, end in eligible)
    if not population:
        raise ValueError("No non-target start sample remains after aside anchor")
    rank = rng.randrange(population)
    for left, right in eligible:
        if rank < right - left:
            start, next_boundary = left + rank, right
            break
        rank -= right - left
    natural_end = start + int(L)
    end = min(natural_end, next_boundary)
    crop_reason = ("session_end" if next_boundary == N else "next_target_speech_start") if end < natural_end else None
    return {
        "start_sample": start, "end_sample": end,
        "natural_end_sample": natural_end, "uncropped_sample_count": int(L),
        "right_truncated": end < natural_end and next_boundary == N,
        "event_truncated": end < natural_end, "crop_reason": crop_reason,
        "placement": "after_anchor_non_target_uniform",
        "placement_policy": "same_voice_aside_free_start_right_crop_v1",
        "anchor_turn_index": anchor_turn_index,
        "eligible_start_intervals": eligible,
        "eligible_start_sample_count": population,
        "next_target_start_sample": next_boundary if next_boundary < N else None,
    }


def _file_fingerprint(path: Path) -> tuple[int, int, int, int, int]:
    stat = path.stat()
    return stat.st_dev, stat.st_ino, stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns


@lru_cache(maxsize=32768)
def _verify_hash_cached(path: str, expected: str, fingerprint: tuple[int, ...]) -> None:
    source = Path(path)
    if _file_fingerprint(source) != fingerprint:
        raise ValueError(f"Source changed before verification: {path}")
    if sha256_file(source) != expected:
        raise ValueError(f"Source SHA256 mismatch: {path}")
    if _file_fingerprint(source) != fingerprint:
        raise ValueError(f"Source changed during verification: {path}")


def _verify_hash(path: str | Path, expected: str) -> tuple[str, tuple[int, ...]]:
    source = Path(path).resolve(strict=True)
    if not isinstance(expected, str) or len(expected) != 64:
        raise ValueError(f"Missing source SHA256: {source}")
    key = (str(source), _file_fingerprint(source))
    _verify_hash_cached(key[0], expected, key[1])
    if _file_fingerprint(source) != key[1]:
        raise ValueError(f"Source changed after verification: {source}")
    return key


@lru_cache(maxsize=512)
def _read_asset_cached(path: str, fingerprint: tuple[int, ...]) -> np.ndarray:
    if _file_fingerprint(Path(path)) != fingerprint:
        raise ValueError(f"Source changed before audio read: {path}")
    data = read_pcm16_wav(Path(path))
    if _file_fingerprint(Path(path)) != fingerprint:
        raise ValueError(f"Source changed during audio read: {path}")
    if not len(data) or not np.isfinite(data).all():
        raise ValueError(f"Invalid source audio: {path}")
    data.setflags(write=False)
    return data


def _source_audio(asset: dict) -> np.ndarray:
    key = _verify_hash(asset["normalized_path"], asset["normalized_sha256"])
    data = _read_asset_cached(*key)
    if _file_fingerprint(Path(key[0])) != key[1]:
        raise ValueError(f"Source changed after audio cache lookup: {key[0]}")
    if len(data) != int(asset["sample_count"]):
        raise ValueError(f"Source sample-count mismatch: {asset['asset_id']}")
    return data


def _active_samples(audio: np.ndarray) -> int:
    peak = float(np.max(np.abs(audio), initial=0.))
    threshold = max(1e-5, peak * .02)
    return int(np.count_nonzero(np.abs(audio) >= threshold))


class UnusableBackgroundError(ValueError):
    """Positions must not be resampled to hide an unusable boundary draw."""
    def __init__(self, active_sample_count: int, events: list[dict]):
        self.reason = "insufficient_background_active_support"
        self.active_sample_count = active_sample_count
        self.events = events
        super().__init__(f"{self.reason}: {active_sample_count} < {MIN_ACTIVE_SAMPLES}")


def _render_event(event: dict, assets: Mapping[str, dict], split: str,
                  recipe: dict | None = None) -> tuple[np.ndarray, dict, np.ndarray]:
    updated = copy.deepcopy(event)
    length = int(updated["end_sample"]) - int(updated["start_sample"])
    unit = np.zeros(length, dtype=np.float32)
    source_active_support = np.zeros(length, dtype=np.bool_)
    if not updated.get("tracks"):
        raise ValueError("An interference event must have explicit source tracks")
    chosen = []
    for track in updated["tracks"]:
        if not track.get("segments"):
            raise ValueError("An interference track has no audible segments")
        for segment in track["segments"]:
            identifier = str(segment["asset_id"])
            asset = assets[identifier]
            if asset.get("split") != split or asset.get("role") != "non_command_speech":
                raise ValueError(f"Wrong split or non-speech source: {identifier}")
            assignment = (recipe or {}).get("background_assignment", {})
            if assignment and asset.get("language") != assignment["language"]:
                raise ValueError(f"Background language mismatch: {identifier}")
            if updated.get("voice_relation") == "reference_clone" or updated.get("type") == "reference_clone" or asset.get("voice_relation") == "reference_clone":
                if recipe is None:
                    raise ValueError("Reference clone requires its target recipe")
                anchor = _validate_clone_asset(asset, recipe, int(updated["anchor_target_turn_index"]))
                if updated["start_sample"] < anchor["end_sample"] or any(
                        updated["start_sample"] < t["end_sample"] and updated["end_sample"] > t["start_sample"]
                        for t in recipe["target_speech_events"]):
                    raise ValueError("Reference clone overlaps its anchor or another target command")
            waveform = _source_audio(asset)
            expected_sha = asset["normalized_sha256"]
            if segment.get("asset_sha256", expected_sha) != expected_sha:
                raise ValueError(f"Segment source SHA256 mismatch: {identifier}")
            source_start, source_end = int(segment["source_start_sample"]), int(segment["source_end_sample"])
            start, end = int(segment["start_sample"]), int(segment["end_sample"])
            if not (0 <= start < end <= length and 0 <= source_start < source_end <= len(waveform)
                    and end - start == source_end - source_start):
                raise ValueError(f"Invalid source/event segment bounds: {identifier}")
            source_rms = active_rms(waveform)
            if source_rms <= 0:
                raise ValueError(f"Silent full source: {identifier}")
            weight = float(segment.get("source_mix_weight", 1.))
            if not math.isfinite(weight) or weight <= 0:
                raise ValueError("Source mix weight must be finite and positive")
            normalization_gain = weight / source_rms
            if "normalization_gain" in segment and not math.isclose(
                    float(segment["normalization_gain"]), normalization_gain, rel_tol=1e-6, abs_tol=1e-9):
                raise ValueError(f"Full-source normalization mismatch: {identifier}")
            unit[start:end] += waveform[source_start:source_end] * np.float32(normalization_gain)
            # A quiet cut prefix must not redefine its own activity threshold:
            # otherwise 10 ms of breath/noise could become a loud background.
            source_threshold = max(1e-5, float(np.max(np.abs(waveform), initial=0.)) * .02)
            source_active_support[start:end] |= np.abs(waveform[source_start:source_end]) >= source_threshold
            segment.update(asset_sha256=expected_sha, normalization_gain=normalization_gain,
                           source_mix_weight=weight, source_full_active_rms=source_rms)
            for key in ("source_group", "transcript"):
                if key in segment and segment[key] != asset.get(key):
                    raise ValueError(f"Segment {key} mismatch: {identifier}")
                if key in asset:
                    segment[key] = asset[key]
            chosen.append(asset)
    fields = (("asset_ids", "asset_id"), ("asset_sha256", "normalized_sha256"),
              ("source_groups", "source_group"), ("speaker_ids", "speaker_id"),
              ("languages", "language"), ("transcripts", "transcript"))
    for field, key in fields:
        values = [asset.get(key) for asset in chosen]
        if field in updated and updated[field] != values:
            raise ValueError(f"Event provenance mismatch: {field}")
        updated[field] = values
    count = min(int(np.count_nonzero(source_active_support)), _active_samples(unit))
    updated.update(active_sample_count=count, boundary_unmeasurable=count < MIN_ACTIVE_SAMPLES,
                   unit_active_rms=active_rms(unit),
                   segment_offsets_relative_to="interference_event_start")
    if count < MIN_ACTIVE_SAMPLES:
        updated["measurement_warning"] = "insufficient_active_samples_without_resampling_position"
    return unit, updated, source_active_support


def mix_scheduled_events(recipe: dict, events: Sequence[dict], assets: Mapping[str, dict],
                         requested_sir_db: float | None = None) -> tuple[np.ndarray, list[dict], dict]:
    """Rebuild original target/noise, mix explicit events, and calibrate jointly.

    No old augmented WAV is read. Segment bounds are already cropped by the
    scheduler and must lie inside their audible event. Source normalization is
    measured over the complete source, never over a possibly silent cut tail.
    Returns float32 audio, a deep-copied enriched event list, and mix metadata.
    """
    requested = float(recipe["requested_background_sir_db"] if requested_sir_db is None else requested_sir_db)
    if not math.isfinite(requested) or not -4 <= requested <= 8:
        raise ValueError("Requested aggregate SIR must be finite and inside [-4, 8] dB")
    for target_event in recipe["target_speech_events"]:
        _verify_hash(target_event["original_audio_path"], target_event["original_audio_sha256"])
    target, utterances = target_track(recipe)
    if not utterances:
        raise ValueError("A session needs at least one complete target utterance")
    reference_rms = active_rms(np.concatenate(utterances))
    if reference_rms <= 0:
        raise ValueError("Target speech has zero active energy")
    bg = recipe["base_background"]
    _verify_hash(bg["path"], bg["sha256"])
    noise = read_background(bg["path"], int(bg["start_window"]) * STRIDE_SAMPLES, len(target))
    base = quantize_pcm16(noise + target).astype(np.float32) / np.float32(32768.)
    background = np.zeros(len(target), dtype=np.float32)
    source_active_support = np.zeros(len(target), dtype=np.bool_)
    updated_events, units = [], []
    for event in events:
        start, end = int(event["start_sample"]), int(event["end_sample"])
        if not 0 <= start < end <= len(target):
            raise ValueError("Interference event outside session")
        unit, updated, event_support = _render_event(event, assets, str(recipe["split"]), recipe)
        background[start:end] += unit
        source_active_support[start:end] |= event_support
        updated_events.append(updated)
        units.append(unit)
    active_count = min(int(np.count_nonzero(source_active_support)), _active_samples(background))
    if active_count < MIN_ACTIVE_SAMPLES:
        raise UnusableBackgroundError(active_count, updated_events)
    background_rms = active_rms(background)
    background_gain = gain_for_db(reference_rms, background_rms, requested)
    background *= np.float32(background_gain)
    mixed = base + background
    peak_before = float(np.max(np.abs(mixed), initial=0.))
    global_scale = min(1., PEAK_LIMIT / max(peak_before, 1e-12))
    mixed *= np.float32(global_scale)
    measured = measured_db(reference_rms, background_rms * background_gain)
    for updated, unit in zip(updated_events, units):
        event_rms = active_rms(unit)
        measurable = not updated["boundary_unmeasurable"] and event_rms > 0
        updated.update(gain=background_gain, background_gain=background_gain,
                       gain_scope="shared_aggregate_background_gain",
                       requested_session_sir_db=requested,
                       measured_event_sir_db=measured_db(reference_rms, event_rms * background_gain) if measurable else None,
                       reference_scope="complete_target_utterances_active",
                       overlapped_target_turn_indices=[int(t.get("turn_index", i))
                           for i, t in enumerate(recipe["target_speech_events"])
                           if updated["start_sample"] < t["end_sample"] and updated["end_sample"] > t["start_sample"]])
    metadata = {
        "policy": POLICY, "requested_background_sir_db": requested,
        "measured_background_sir_db": measured,
        "sir_scope": "aggregate_all_third_party_speech_active_rms",
        "reference_scope": "complete_target_utterances_active",
        "target_reference_active_rms": reference_rms,
        "background_unit_active_rms": background_rms,
        "background_active_sample_count": active_count,
        "minimum_active_support_scope": "union_of_complete_source_relative_activity_masks_and_aggregate_activity",
        "background_gain": background_gain,
        "peak_before_global_scale": peak_before, "global_scale": global_scale,
        "global_scale_scope": "entire_mixture_including_target_and_base_noise",
        "target_content_and_timing_preserved": True,
        "target_amplitude_preserved": global_scale == 1.,
        "normalization_scope": "complete_source_before_boundary_crop",
        "boundary_unmeasurable_event_count": sum(e["boundary_unmeasurable"] for e in updated_events),
        "minimum_background_active_samples": MIN_ACTIVE_SAMPLES,
        "source_audio_sha256_verified": True,
        "base_audio_stats": audio_stats(base),
        "audio_stats": audio_stats(mixed),
    }
    return mixed, updated_events, metadata


def schedule_seed(recipe: dict, assignment: dict, seed: int,
                  component: str, event_index: int = 0) -> int:
    """Independent streams; adding a source draw cannot alter placement or SIR."""
    return stable_u64(POLICY, seed, recipe.get("session_signature", recipe.get("session_id", "")),
                      assignment["session_type"], assignment["language"], component, event_index)


def _validate_clone_asset(asset: dict, recipe: dict, anchor_index: int) -> dict:
    if asset.get("eligible_for_mixing") is not True:
        raise ValueError("Reference clone is not eligible_for_mixing")
    anchors = [event for i, event in enumerate(recipe["target_speech_events"])
               if int(event.get("turn_index", i)) == anchor_index]
    if len(anchors) != 1:
        raise ValueError("Reference clone anchor must identify exactly one target turn")
    anchor = anchors[0]
    if asset.get("reference_sha256") != anchor["original_audio_sha256"]:
        raise ValueError("Reference clone anchor SHA256 mismatch")
    if not asset.get("reference_audio") or Path(asset["reference_audio"]).resolve() != Path(anchor["original_audio_path"]).resolve():
        raise ValueError("Reference clone anchor audio path mismatch")
    if asset.get("split") != recipe["split"] or asset.get("role") != "non_command_speech":
        raise ValueError("Reference clone split/role mismatch")
    return anchor


def _segment(asset: dict, start: int, source_end: int, weight: float) -> dict:
    return {
        "asset_id": asset["asset_id"], "asset_sha256": asset["normalized_sha256"],
        "source_group": asset["source_group"], "speaker_id": asset["speaker_id"],
        "language": asset["language"], "speech_domain": asset.get("speech_domain"),
        "transcript": asset["transcript"], "source_sample_count": int(asset["sample_count"]),
        "source_start_sample": 0, "source_end_sample": source_end,
        "start_sample": start, "end_sample": start + source_end,
        "source_mix_weight": weight,
    }


def _finish_schedule(event: dict, natural_tracks: list[dict], assets: Mapping[str, dict]) -> dict:
    """Crop only the audible end; preserve planned track identities in metadata."""
    length = int(event["end_sample"]) - int(event["start_sample"])
    tracks = []
    event["planned_track_count"] = len(natural_tracks)
    event["planned_speaker_ids"] = [track["speaker_id"] for track in natural_tracks]
    for track in natural_tracks:
        segments = []
        for segment in track["segments"]:
            start = int(segment["start_sample"])
            if start >= length:
                continue
            current = copy.deepcopy(segment)
            actual_end = min(length, int(segment["end_sample"]))
            current.update(end_sample=actual_end, source_end_sample=actual_end - start)
            current["boundary_truncated"] = actual_end < int(segment["end_sample"])
            current["natural_end_sample"] = int(segment["end_sample"])
            segments.append(current)
        if segments:
            tracks.append({**track, "segments": segments})
    if not tracks:
        raise ValueError("Scheduled event has no source onset; first track must start at zero")
    event["tracks"] = tracks
    event["track_count"] = len(tracks)
    event["segment_offsets_relative_to"] = "interference_event_start"
    chosen = [assets[s["asset_id"]] for t in tracks for s in t["segments"]]
    for field, key in (("asset_ids", "asset_id"), ("asset_sha256", "normalized_sha256"),
                       ("source_groups", "source_group"), ("speaker_ids", "speaker_id"),
                       ("languages", "language"), ("transcripts", "transcript")):
        event[field] = [asset.get(key) for asset in chosen]
    return event


def schedule_events(recipe: dict, assignment: dict, assets: Mapping[str, dict] | Sequence[dict],
                    seed: int, tts_assets: Mapping[str, dict] | None = None) -> list[dict]:
    """Schedule six speech classes without opening or changing any audio file.

    The first speaker starts at event offset zero; other tracks have independent
    0--0.3 s offsets. Continuous events contain complete natural utterances with
    0.1--0.4 s gaps, except for the allowed crop at the session boundary. A track
    stops when its remaining unused utterances no longer fit; it never silently
    reuses an utterance before exhausting its available pool.

    For an independent SIR draw use truncated_sir(random.Random(schedule_seed(
    recipe, assignment, seed, "sir"))). No SIR draw is consumed here.
    """
    kind, language = assignment["session_type"], assignment["language"]
    if kind not in dict(CLASS_WEIGHTS) or language not in {"zh", "en"}:
        raise ValueError("Unknown session class or background language")
    if assignment.get("split", recipe["split"]) != recipe["split"]:
        raise ValueError("Assignment split differs from target recipe")
    for key in ("session_id", "session_signature"):
        if key in assignment and key in recipe and assignment[key] != recipe[key]:
            raise ValueError(f"Assignment {key} differs from target recipe")
    N = int(recipe["audio"]["sample_count"])
    _positive_samples(N, 1)
    rows = list(assets.values()) if isinstance(assets, Mapping) else list(assets)
    by_id = {str(row["asset_id"]): row for row in rows}
    if len(by_id) != len(rows):
        raise ValueError("Duplicate asset IDs in selected real registry")
    real_rows = sorted((row for row in rows if row.get("split") == recipe["split"]
                        and row.get("language") == language and row.get("role") == "non_command_speech"
                        and row.get("voice_relation") != "reference_clone" and int(row["sample_count"]) > 0),
                       key=lambda row: str(row["asset_id"]))

    def rng(component: str, index: int = 0) -> random.Random:
        return random.Random(schedule_seed(recipe, assignment, seed, component, index))

    def eligible(domain: str, short: bool) -> list[dict]:
        result = [row for row in real_rows if row.get("speech_domain") == domain
                  and (not short or (int(row["sample_count"]) <= 8 * SAMPLE_RATE
                                     and row.get("planned_usage") != "continuous_only"))]
        if not result:
            raise ValueError(f"Missing {recipe['split']}/{language}/{domain} {'short' if short else 'continuous'} sources")
        return result

    count_rng, type_rng = rng("class_count"), rng("event_types")
    if kind == "single_short":
        types = ["single"]
    elif kind == "multi_single":
        types = ["single"] * count_rng.randint(2, 4)
    elif kind == "multi_babble":
        types = ["babble"] * count_rng.randint(2, 3)
    elif kind == "mixed_short":
        types = ["single", "babble"] + [type_rng.choice(("single", "babble")) for _ in range(count_rng.randint(3, 5) - 2)]
        type_rng.shuffle(types)
    elif kind == "continuous":
        types = ["continuous"]
    else:
        types = ["reference_clone"] + [type_rng.choice(("single", "babble")) for _ in range(count_rng.randint(1, 2))]

    result = []
    for event_index, event_type in enumerate(types):
        source_rng, offset_rng = rng("source", event_index), rng("offset", event_index)
        event = {"event_id": f"event_{event_index:02d}", "event_index": event_index,
                 "event_seed": schedule_seed(recipe, assignment, seed, "source", event_index),
                 "placement_seed": schedule_seed(recipe, assignment, seed, "placement", event_index),
                 "policy": POLICY, "session_type": kind, "language": language,
                 "track_offset_policy": "first_zero_others_uniform_0_to_0.3_seconds"}
        if event_type == "reference_clone":
            job_id = assignment["tts_job_id"]
            if tts_assets is None or job_id not in tts_assets:
                raise ValueError(f"Missing qualified TTS clone job: {job_id}")
            clone = tts_assets[job_id]
            if clone.get("job_id", job_id) != job_id or clone.get("language") != language:
                raise ValueError("TTS job binding or background language mismatch")
            anchor_index = int(assignment["anchor_target_turn_index"])
            _validate_clone_asset(clone, recipe, anchor_index)
            L = int(clone["sample_count"])
            by_id[clone["asset_id"]] = clone
            geometry = placement_same_voice_aside(N, L, recipe["target_speech_events"], anchor_index,
                                                 rng("placement", event_index))
            natural_tracks = [{"track_index": 0, "speaker_id": clone["speaker_id"], "language": language,
                               "start_offset_samples": 0, "segments": [_segment(clone, 0, L, 1.)]}]
            event.update(type="reference_clone", voice_relation="reference_clone", tts_job_id=job_id,
                         anchor_target_turn_index=anchor_index, speech_domain=clone.get("speech_domain", "aside"),
                         **geometry)
        else:
            domain = rng("domain", event_index).choice(("conversation", "read"))
            pool = eligible(domain, event_type != "continuous")
            grouped = defaultdict(list)
            for asset in pool:
                if asset.get("speaker_id"):
                    grouped[str(asset["speaker_id"])].append(asset)
            if event_type == "single":
                asset = source_rng.choice(pool)
                L = int(asset["sample_count"])
                natural_tracks = [{"track_index": 0, "speaker_id": asset["speaker_id"], "language": language,
                                   "start_offset_samples": 0, "segments": [_segment(asset, 0, L, 1.)]}]
                event["type"] = "foreground_non_command"
            elif event_type == "babble":
                track_count = source_rng.randint(2, 3)
                if len(grouped) < track_count:
                    raise ValueError(f"Need {track_count} different short speakers in {language}/{domain}")
                speakers = source_rng.sample(sorted(grouped), track_count)
                natural_tracks = []
                for track_index, speaker in enumerate(speakers):
                    asset = source_rng.choice(grouped[speaker])
                    offset = 0 if track_index == 0 else offset_rng.randint(0, round(.3 * SAMPLE_RATE))
                    natural_tracks.append({"track_index": track_index, "speaker_id": speaker, "language": language,
                                           "start_offset_samples": offset,
                                           "segments": [_segment(asset, offset, int(asset["sample_count"]), 1 / math.sqrt(track_count))]})
                L = max(s["end_sample"] for t in natural_tracks for s in t["segments"])
                event["type"] = "babble"
            else:
                L = rng("continuous_length", event_index).randint(math.ceil(.6 * N), math.floor(1.2 * N))
                grouped = {speaker: [row for row in group if int(row["sample_count"]) <= L - round(.3 * SAMPLE_RATE)]
                           for speaker, group in grouped.items()}
                grouped = {speaker: group for speaker, group in grouped.items() if len(group) >= 2}
                track_count = source_rng.randint(2, 4)
                if len(grouped) < track_count:
                    raise ValueError(f"Need {track_count} continuous speakers with two fitting clips in {language}/{domain}")
                speakers = source_rng.sample(sorted(grouped), track_count)
                natural_tracks = []
                for track_index, speaker in enumerate(speakers):
                    track_rng = rng(f"continuous_track_{speaker}", event_index)
                    offset = 0 if track_index == 0 else offset_rng.randint(0, round(.3 * SAMPLE_RATE))
                    position, previous, cycle = offset, None, 0
                    unused = {row["asset_id"] for row in grouped[speaker]}
                    segments = []
                    while position < L:
                        if not unused:
                            unused = {row["asset_id"] for row in grouped[speaker]}
                            cycle += 1
                        fitting = [row for row in grouped[speaker] if row["asset_id"] in unused
                                   and row["asset_id"] != previous and int(row["sample_count"]) <= L - position]
                        if not fitting:
                            break
                        asset = track_rng.choice(fitting)
                        segment = _segment(asset, position, int(asset["sample_count"]), 1 / math.sqrt(track_count))
                        segment.update(reused_asset=cycle > 0, source_pool_cycle=cycle)
                        segments.append(segment)
                        unused.remove(asset["asset_id"])
                        previous = asset["asset_id"]
                        position = int(segment["end_sample"]) + track_rng.randint(round(.1 * SAMPLE_RATE), round(.4 * SAMPLE_RATE))
                    if not segments:
                        raise ValueError("Continuous track lacks a complete initial utterance")
                    natural_tracks.append({"track_index": track_index, "speaker_id": speaker, "language": language,
                                           "start_offset_samples": offset, "available_unique_asset_count": len(grouped[speaker]),
                                           "segments": segments})
                event.update(type="babble_continuous", synthesis_policy="complete_utterance_tracks_with_session_right_crop_v5",
                             inter_utterance_gap_samples=[round(.1 * SAMPLE_RATE), round(.4 * SAMPLE_RATE)])
            event.update(speech_domain=domain, **placement_uniform(N, L, rng("placement", event_index)))
        result.append(_finish_schedule(event, natural_tracks, by_id))
    return result