输入清单 + SHA-256 + 角色轨映射
             ↓
ffprobe 体检 → FFmpeg 分轨/规范化 → 16kHz mono PCM
             ↓
Silero VAD → 用户轨 speech segments / AI 轨 speech segments
             ↓
用户片段合并 + EOU/语义 + 应答义务 → response window
             ↓
AI 轨无 speech + 解码/TTS/播放状态 → 无声候选 + 原因码
             ↓
人工复核 / 统计聚合 / 回放金标

$ cd practice-hub/ffmpeg-silero-vad
$ python3.12 -m venv .venv
$ .venv/bin/python -m pip install --upgrade pip
$ .venv/bin/python -m pip install -r requirements.txt

# 官方 6.2.1 提供 ONNX CPU extra；需要 ONNX 时可用
$ .venv/bin/python -m pip install "silero-vad[onnx-cpu]==6.2.1"

# 如需与本次验证环境完全对齐，显式锁定运行时
$ .venv/bin/python -m pip install \
    "torch==2.13.0" "torchaudio==2.11.0" "onnxruntime==1.29.0"

$ ffmpeg -version
$ ffprobe -version
$ .venv/bin/python -c "import silero_vad; print(silero_vad.__version__)"

$ ffprobe -v error \
  -show_entries \
  format=format_name,duration,bit_rate:stream=index,codec_type,codec_name,sample_rate,channels,channel_layout \
  -of json ./recordings/call.wav

$ ffmpeg -hide_banner -loglevel error -nostdin -y \
  -i ./recordings/call.wav -map 0:a:0 -vn \
  -ac 1 -ar 16000 -c:a pcm_s16le ./work/normalized.wav

# 例：左声道=用户，右声道=AI；映射必须来自录音系统真值
$ ffmpeg -hide_banner -loglevel error -nostdin -y \
  -i ./recordings/call-stereo.wav \
  -filter_complex "[0:a]channelsplit=channel_layout=stereo[user][ai]" \
  -map "[user]" -ar 16000 -c:a pcm_s16le ./work/user.wav \
  -map "[ai]"   -ar 16000 -c:a pcm_s16le ./work/ai.wav

$ ffmpeg -hide_banner -loglevel error -nostdin -y \
  -i ./recordings/call-multistream.mka \
  -map 0:a:0 -ac 1 -ar 16000 -c:a pcm_s16le ./work/user.wav \
  -map 0:a:1 -ac 1 -ar 16000 -c:a pcm_s16le ./work/ai.wav

# 把输入路径替换为自己的合法音频；下方数值回执来自本次 run 1
$ cd practice-hub/ffmpeg-silero-vad
$ .venv/bin/python -m ffmpeg_silero_vad \
  /path/to/call.wav \
  --output-dir ./outputs/run-01 \
  --backend jit \
  --threshold 0.5 \
  --min-speech-duration-ms 250 \
  --min-silence-duration-ms 100 \
  --speech-pad-ms 30

{
  "ok": true,
  "speech_ratio": 0.688628,
  "speech_segment_count": 2,
  "total_elapsed_ms": 797.689
}

vad-output/
├── normalized.wav   # mono / 16kHz / PCM s16le
├── result.json      # 媒体、参数、后端、区间、哈希、耗时
└── segments.csv     # speech / silence 时间线

{
  "schema_version": "1.0",
  "pipeline": "ffmpeg-silero-vad",
  "input_audio": {
    "filename": "two-turn.wav",
    "sha256": "…",
    "ffprobe": { "streams": […], "format": {…} }
  },
  "normalized_audio": {
    "sample_rate_hz": 16000,
    "channels": 1,
    "codec": "pcm_s16le",
    "duration_seconds": 9.23575,
    "sha256": "…"
  },
  "parameters": {
    "threshold": 0.5,
    "min_speech_duration_ms": 250,
    "min_silence_duration_ms": 100,
    "speech_pad_ms": 30,
    "backend": "jit"
  },
  "model_backend": {
    "engine": "silero-vad",
    "package_version": "6.2.1",
    "execution_backend": "jit",
    "torch_num_threads": 1
  },
  "summary": {
    "speech_segment_count": 2,
    "speech_ratio": 0.688628
  },
  "speech_segments": [{
    "start_sample": 15904,
    "end_sample": 58848,
    "start_ms": 994.0,
    "end_ms": 3678.0
  }],
  "runtime": {
    "scope": "in_process_run_through_result_assembly",
    "excludes": ["python_process_startup", "cli_argument_parsing",
                 "segments_csv_and_result_json_write", "stdout_and_process_exit"],
    "ffmpeg_elapsed_ms": 34.35,
    "vad_elapsed_ms": 731.301,
    "total_elapsed_ms": 797.689
  }
}

# 逻辑示意：真实调度器应用 manifest / 数据库代替文件遍历
job_key = SHA256(input_bytes)
        + role_mapping_version
        + ffmpeg_profile_version
        + silero_package_version
        + model_sha256
        + parameter_set_version
        + output_schema_version

if completed(job_key) and artifacts_match_hashes:
    SKIP_AS_IDEMPOTENT
elif previous_exit_code in (4, 2):
    QUARANTINE_WITH_REASON
elif node_failure and retry_count < retry_limit:
    RETRY_WITH_BACKOFF
else:
    RUN_IN_ISOLATED_OUTPUT_DIR

RuntimeError: torchaudio version 2.11.0 requires torchcodec for audio I/O.
Install torchcodec or pin torchaudio < 2.9

eou_event = {
  "call_id": "anon-call-id",
  "turn_id": "turn-0042",
  "user_acoustic_end_ms": 18420,
  "eou_commit_ms": 19160,
  "eou_reason": "vad_stop+asr_final+semantic_complete",
  "eou_confidence": 0.93,
  "policy_version": "eou-cn-sales-v3"
}

window_start = eou_commit_ms
window_stop  = min(next_user_speech_start_ms,
                   hangup_ms, transfer_ms, policy_max_observe_ms)

warning_deadline = max(policy_warning_ms,
                       Q95(normal_response_gap | scenario) + safety_margin_ms)
failure_deadline = max(policy_failure_ms,
                       Q99(normal_response_gap | scenario) + safety_margin_ms)

# Q95/Q99 只能来自校准集中的正常应答；隐藏测试集不参与阈值选择。

{
  "schema_version": "voice-trace-1.0",
  "call_id": "anon-call-id",
  "turn_id": "turn-0042",
  "response_attempt_id": "resp-01",
  "trace_id": "trace-...",
  "event_name": "rtp_first_packet_sent",
  "component": "media-gateway",
  "status": "ok",
  "event_time_utc": "2026-09-01T01:23:45.678Z",
  "t_mono_ms": 3819221.447,
  "clock_id": "host-media-03/boot-8f2",
  "payload_bytes": 172,
  "codec": "opus",
  "ssrc": "hashed-ssrc",
  "error_code": null
}

if not track_contract_passed:
    return INPUT_OR_TRACK_INVALID, abstain
if role_confidence < role_threshold:
    return ROLE_UNCERTAIN, abstain
if not user_valid_speech or eou_state != "committed":
    return EOU_NOT_COMMITTED, no_response_opportunity
if not expected_ai_response:
    return NO_RESPONSE_REQUIRED, valid_negative

ai_onset = first_ai_audible_onset(window)
if ai_onset and ai_onset <= warning_deadline:
    return OK
if ai_onset and ai_onset <= failure_deadline:
    return DELAYED_AI_RESPONSE

if not llm_output:          return LLM_EMPTY_OR_TIMEOUT
if not tts_audio:           return TTS_EMPTY_OR_FAILED
if not decoder_pcm:         return DECODE_FAILED
if not downstream_rtp:      return RTP_NOT_SENT
if not playout_started:     return PLAYOUT_MUTED_OR_DROPPED
if not recorder_ai_onset:   return RECORDING_OR_ROUTE_GAP
return SUSPECTED_NO_RESPONSE_AUDIO

gold_event = {
  "call_id": "anon-call-id",
  "turn_id": "turn-0042",
  "response_attempt_id": "resp-01",
  "user_speech": [17120, 18420],
  "eou_ms": 19160,
  "expected_ai_response": true,
  "scenario": "simple_qa",
  "warning_deadline_ms": 20660,
  "failure_deadline_ms": 22160,
  "ai_audible_onset_ms": null,
  "label": "confirmed_silent_failure",
  "root_cause": "TTS_EMPTY_OR_FAILED",
  "evidence_level": "A",
  "annotator_1": "blind",
  "annotator_2": "blind",
  "adjudication": "agreed"
}

loss = C_fn   * missed_silent_failure
     + C_fp   * false_review_candidate
     + C_root * wrong_root_cause
     + C_eou  * premature_eou
     + C_load * human_review_minutes

# 成本系数由业务、质量、平台和人工复核团队共同批准；
# 不把单一 F1 当作全部业务价值。

Candidate Precision = true_candidates / all_candidates
Event Recall        = detected_true_failures / all_true_failures
Root-cause Accuracy = correct_reason_code / full-trace_failures
EOU early-cut rate  = premature_commits / committed_turns
Review load         = candidates / 1000_calls
Coverage            = classifiable_opportunities / all_opportunities

com.example.silentqa
├── api/
│   ├── SilentQaController.java        # 202 受理与结果查询
│   └── SilentQaRequest.java           # Jakarta Validation
├── application/
│   ├── SilentQaApplicationService.java
│   └── QaJobDispatcher.java           # DB outbox / MQ / 有界 POC executor
├── domain/
│   ├── VadEngine.java                 # 可替换端口
│   ├── ResponseOpportunityEvaluator.java
│   ├── TraceAssembler.java
│   └── QaDecision.java
└── infrastructure/
    ├── worker/PythonCliVadEngine.java
    ├── onnx/OnnxVadEngine.java        # 通过金标等价门后再启用
    ├── persistence/QaJobRepository.java
    └── messaging/ReviewQueuePublisher.java

public record QaJob(
    String jobId,
    String callId,
    URI userTrack,
    URI aiTrack,
    String inputSha256,
    String roleMappingVersion,
    String policyVersion,
    String traceId
) {}

public interface VadEngine {
    VadEvidence detect(QaJob job, VadProfile profile) throws VadEngineException;
}

public record QaDecision(
    String responseOpportunityId,
    String label,
    String reasonCode,
    String evidenceLevel,
    BigDecimal confidence,
    Instant windowStart,
    Instant windowEnd,
    List<String> missingEvents,
    String decisionBundleVersion
) {}

@Component
final class PythonCliVadEngine implements VadEngine {
    VadEvidence detect(QaJob job, VadProfile profile) throws Exception {
        Path input = storage.materializeAuthorized(job.userTrack(), job.inputSha256());
        Path work = workRoot.resolve(job.jobId());       // 每任务唯一目录
        Files.createDirectory(work);                    // 父目录由服务启动时创建

        List<String> command = List.of(
            pythonExecutable, "-m", "ffmpeg_silero_vad", input.toString(),
            "--output-dir", work.toString(),
            "--backend", "onnx",
            "--threshold", profile.threshold().toPlainString(),
            "--min-speech-duration-ms", String.valueOf(profile.minSpeechMs()),
            "--min-silence-duration-ms", String.valueOf(profile.minSilenceMs()),
            "--speech-pad-ms", String.valueOf(profile.speechPadMs())
        );

        Process process = new ProcessBuilder(command)    // 不经过 shell
            .directory(pythonPackageDir.toFile())
            .redirectOutput(work.resolve("stdout.json").toFile())
            .redirectError(work.resolve("stderr.log").toFile())
            .start();

        if (!process.waitFor(timeout.toMillis(), TimeUnit.MILLISECONDS)) {
            process.descendants().forEach(ProcessHandle::destroyForcibly);
            process.destroyForcibly();
            throw new VadEngineException("VAD_TIMEOUT");
        }
        if (process.exitValue() != 0) {
            throw mapCliExitCode(process.exitValue(), work.resolve("stderr.log"));
        }
        return verifyHashesAndRead(work.resolve("result.json"), job, profile);
    }
}

public interface VadProvider extends StreamingInputProvider {}

@Component
final class SileroStreamingVadProvider implements VadProvider {
    private final ConcurrentMap<String, VadSession> sessions = new ConcurrentHashMap<>();

    public void open(String sessionId, int sampleRate) {
        sessions.put(sessionId, VadSession.start(sampleRate, queueCapacity));
    }

    public void accept(String sessionId, long generation, PcmPacket packet) {
        VadSession state = requireSession(sessionId);
        byte[] pcmCopy = packet.pcm16le().clone();
        if (!state.offer(new VadFrame(generation, packet.timestampNs(),
                                      packet.sampleRate(), pcmCopy))) {
            metrics.increment("silent_qa_vad_frame_dropped_total");
        }                                                   // 立即返回
    }

    public void interrupt(String sessionId, long generation, String reason) {
        requireSession(sessionId).resetTo(generation);       // 清 state/context/旧帧
    }

    public void close(String sessionId) {
        Optional.ofNullable(sessions.remove(sessionId)).ifPresent(VadSession::close);
    }
}

silent-qa:
  mode: ${SILENT_QA_MODE:python-worker}
  python-executable: ${SILENT_QA_PYTHON:/opt/silent-qa/venv/bin/python}
  python-package-dir: ${SILENT_QA_PACKAGE:/opt/silent-qa/app}
  work-root: ${SILENT_QA_WORK_ROOT:/var/lib/silent-qa/work}
  timeout: ${SILENT_QA_TIMEOUT:5m}
  max-concurrency: ${SILENT_QA_MAX_CONCURRENCY:4}
  queue-capacity: ${SILENT_QA_QUEUE_CAPACITY:100}
  vad:
    backend: onnx
    threshold: 0.50
    min-speech-ms: 250
    min-silence-ms: 100
    speech-pad-ms: 30
    profile-version: silero-cn-phone-poc-v1

# 每次策略发布都生成不可变版本包
decision_bundle = {
  "role_mapping_version": "role-map-v2",
  "vad_profile_version": "silero-cn-phone-v4",
  "eou_policy_version": "eou-cn-sales-v3",
  "response_window_version": "window-scenario-v2",
  "trace_schema_version": "voice-trace-1.0",
  "reason_code_version": "silent-reason-v1",
  "gold_set_version": "phone-gold-2026q3",
  "code_commit": "immutable-revision"
}