/**
 * 均匀采样：每N帧取一帧
 * 问题：可能错过重要内容，也可能采样到大量冗余帧（如静止场景）
 */
public List<VideoFrame> uniformSample(String videoPath, int intervalSeconds) {
    List<VideoFrame> frames = new ArrayList<>();
    
    try (FFmpegFrameGrabber grabber = new FFmpegFrameGrabber(videoPath)) {
        grabber.start();
        
        double totalDuration = grabber.getLengthInTime() / 1000000.0; // 转为秒
        double fps = grabber.getFrameRate();
        int totalFrames = (int)(totalDuration * fps);
        int interval = (int)(intervalSeconds * fps);
        
        for (int frameIdx = 0; frameIdx < totalFrames; frameIdx += interval) {
            grabber.setVideoFrameNumber(frameIdx);
            Frame frame = grabber.grabImage();
            
            if (frame != null) {
                frames.add(VideoFrame.builder()
                    .frameIndex(frameIdx)
                    .timestamp(frameIdx / fps)
                    .imageData(convertToBytes(frame))
                    .build());
            }
        }
        
        grabber.stop();
    }
    
    return frames;
}

策略2：场景切换检测采样（推荐核心策略）

@Component
public class SceneChangeDetector {
    
    /**
     * 基于场景切换的智能采样
     * 核心思路：检测相邻帧之间的差异，超过阈值说明场景切换，需要采样
     */
    public List<VideoFrame> sceneBasedSample(String videoPath, 
                                               SceneSamplingConfig config) {
        List<VideoFrame> keyFrames = new ArrayList<>();
        
        try (FFmpegFrameGrabber grabber = new FFmpegFrameGrabber(videoPath)) {
            grabber.start();
            
            Mat previousFrame = null;
            int frameIdx = 0;
            double lastSampledTime = -config.getMinInterval(); // 确保第一帧被采样
            
            Frame frame;
            while ((frame = grabber.grabImage()) != null) {
                double currentTime = grabber.getTimestamp() / 1000000.0;
                Mat currentMat = convertToMat(frame);
                
                boolean shouldSample = false;
                String sampleReason = "";
                
                if (previousFrame == null) {
                    // 第一帧必须采样
                    shouldSample = true;
                    sampleReason = "FIRST_FRAME";
                } else if (currentTime - lastSampledTime >= config.getMaxInterval()) {
                    // 超过最大间隔，强制采样（防止长静止场景被跳过）
                    shouldSample = true;
                    sampleReason = "MAX_INTERVAL";
                } else if (currentTime - lastSampledTime >= config.getMinInterval()) {
                    // 检测场景切换
                    double changeScore = calculateFrameDifference(previousFrame, currentMat);
                    
                    if (changeScore > config.getSceneChangeThreshold()) {
                        shouldSample = true;
                        sampleReason = "SCENE_CHANGE:" + String.format("%.2f", changeScore);
                    }
                }
                
                if (shouldSample) {
                    keyFrames.add(VideoFrame.builder()
                        .frameIndex(frameIdx)
                        .timestamp(currentTime)
                        .imageData(matToBytes(currentMat))
                        .sampleReason(sampleReason)
                        .build());
                    
                    lastSampledTime = currentTime;
                }
                
                previousFrame = currentMat;
                frameIdx++;
            }
            
            grabber.stop();
        }
        
        return keyFrames;
    }
    
    /**
     * 计算两帧之间的差异程度
     * 方法：直方图比较（快速）+ 结构相似性（更准确）
     */
    private double calculateFrameDifference(Mat frame1, Mat frame2) {
        // 转为灰度图
        Mat gray1 = new Mat(), gray2 = new Mat();
        cvtColor(frame1, gray1, COLOR_BGR2GRAY);
        cvtColor(frame2, gray2, COLOR_BGR2GRAY);
        
        // 方法1：直方图相关性（快速，适合初筛）
        Mat hist1 = new Mat(), hist2 = new Mat();
        calcHist(new MatVector(gray1), new int[]{0}, new Mat(), hist1, 
                 new int[]{256}, new float[]{0, 256});
        calcHist(new MatVector(gray2), new int[]{0}, new Mat(), hist2, 
                 new int[]{256}, new float[]{0, 256});
        
        double correlation = compareHist(hist1, hist2, CV_COMP_CORREL);
        
        // 相关性1.0表示完全相同，越小说明差异越大
        // 转换：差异分数 = 1 - 相关性
        return 1.0 - correlation;
    }
    
    /**
     * 更精确的场景切换检测：结构相似性（SSIM）
     * 用于对差异分数较高的帧做二次确认
     */
    private double calculateSSIM(Mat frame1, Mat frame2) {
        Mat f1 = new Mat(), f2 = new Mat();
        frame1.convertTo(f1, CV_32F);
        frame2.convertTo(f2, CV_32F);
        
        // SSIM计算（简化版）
        Mat mu1 = new Mat(), mu2 = new Mat();
        GaussianBlur(f1, mu1, new Size(11, 11), 1.5);
        GaussianBlur(f2, mu2, new Size(11, 11), 1.5);
        
        // ... SSIM完整计算较复杂，这里省略
        // 实际可以用OpenCV的quality模块：QualitySSIM.compute
        
        return 0.0; // 返回SSIM值
    }
}

策略3：内容感知采样（高级）

@Component
public class ContentAwareSampler {
    
    @Autowired
    private VisionModelClient visionClient;
    
    /**
     * 两阶段采样：
     * 第一阶段：场景切换检测，得到候选关键帧
     * 第二阶段：视觉模型评估每帧的信息量，过滤低信息帧
     */
    public List<VideoFrame> contentAwareSample(List<VideoFrame> candidateFrames) {
        
        if (candidateFrames.size() <= 10) return candidateFrames; // 帧数少直接用
        
        // 批量评估每帧的信息量（一次调用多帧，节省API成本）
        List<FrameScore> scores = batchScoreFrames(candidateFrames);
        
        // 按时间段选取信息量最高的帧
        List<VideoFrame> selectedFrames = selectTopFramesBySegment(candidateFrames, scores);
        
        return selectedFrames;
    }
    
    /**
     * 批量评估帧的信息量
     * 低信息量的帧（空白页、黑屏、过渡帧）可以过滤掉
     */
    private List<FrameScore> batchScoreFrames(List<VideoFrame> frames) {
        List<FrameScore> scores = new ArrayList<>();
        
        // 每次评估5帧（用一个API调用）
        int batchSize = 5;
        for (int i = 0; i < frames.size(); i += batchSize) {
            List<VideoFrame> batch = frames.subList(i, 
                Math.min(i + batchSize, frames.size()));
            
            scores.addAll(scoreBatch(batch));
        }
        
        return scores;
    }
    
    private List<FrameScore> scoreBatch(List<VideoFrame> batch) {
        // 构建多图评估Prompt
        // 注：这里需要支持多图输入的VLM，如GPT-4V
        
        String prompt = String.format("""
            以下是视频中的%d帧截图，请为每帧评估信息量：
            
            评估标准：
            - 10分：包含完整、清晰的内容（PPT文字、产品展示、人物讲解等）
            - 5分：有内容但不完整（过渡帧、部分信息）
            - 1分：几乎没有信息量（纯黑/纯白/模糊过渡）
            
            返回JSON数组（只返回分数）：
            [{"frame_index": 0, "score": 8}, ...]
            """, batch.size());
        
        // 调用多图API
        List<byte[]> frameImages = batch.stream()
            .map(VideoFrame::getImageData)
            .collect(Collectors.toList());
        
        String response = visionClient.analyzeMultiple(frameImages, prompt);
        return parseFrameScores(response, batch);
    }
}

音视频联合分析

视频的音频往往包含大量信息，不能只看画面：

@Component
public class AudioVideoAlignedAnalyzer {
    
    @Autowired
    private WhisperClient whisperClient;
    
    @Autowired
    private VisionModelClient visionClient;
    
    /**
     * 音视频对齐分析
     * 核心：把音频转录的时间戳与视频帧的时间戳对齐
     */
    public AlignedAnalysisResult analyze(String videoPath) {
        
        // 1. 提取音频
        byte[] audioData = extractAudio(videoPath);
        
        // 2. 音频转录（含时间戳）
        TranscriptionResult transcription = whisperClient.transcribeWithTimestamps(audioData);
        
        // 3. 关键帧采样
        List<VideoFrame> keyFrames = sceneDetector.sceneBasedSample(videoPath,
            SceneSamplingConfig.defaults());
        
        // 4. 音视频对齐
        List<AlignedSegment> alignedSegments = alignAudioVideo(
            keyFrames, transcription.getSegments());
        
        // 5. 联合分析每个对齐段
        List<SegmentAnalysis> analyses = alignedSegments.parallelStream()
            .map(this::analyzeSegment)
            .collect(Collectors.toList());
        
        // 6. 整体汇聚
        return aggregateAnalyses(analyses, transcription.getFullText());
    }
    
    /**
     * 音视频时间对齐
     * 给每个视频帧段，找到对应的音频文字
     */
    private List<AlignedSegment> alignAudioVideo(
            List<VideoFrame> videoFrames,
            List<TranscriptionSegment> audioSegments) {
        
        List<AlignedSegment> aligned = new ArrayList<>();
        
        for (int i = 0; i < videoFrames.size(); i++) {
            VideoFrame frame = videoFrames.get(i);
            double frameStart = frame.getTimestamp();
            double frameEnd = (i + 1 < videoFrames.size()) ? 
                videoFrames.get(i + 1).getTimestamp() : frameStart + 10;
            
            // 找到这个时间段内的音频文字
            String audioText = audioSegments.stream()
                .filter(seg -> seg.getStart() >= frameStart && 
                               seg.getEnd() <= frameEnd + 2) // 允许2秒重叠
                .map(TranscriptionSegment::getText)
                .collect(Collectors.joining(" "));
            
            aligned.add(AlignedSegment.builder()
                .frame(frame)
                .startTime(frameStart)
                .endTime(frameEnd)
                .audioText(audioText)
                .build());
        }
        
        return aligned;
    }
    
    /**
     * 单个对齐段的联合分析
     */
    private SegmentAnalysis analyzeSegment(AlignedSegment segment) {
        String prompt = String.format("""
            以下是视频某一段的截图和同时间段的音频文字：
            
            音频文字："%s"
            
            请根据截图和音频文字，分析这一段的内容：
            1. 这段主要在说/展示什么
            2. 截图中的视觉信息与音频是否一致，有无补充
            3. 关键信息点（数字、术语、结论等）
            4. 这段内容的类型（介绍/演示/讲解/Q&A等）
            
            返回JSON：
            {
              "content_summary": "内容摘要（1-2句话）",
              "key_information": ["关键信息1", "关键信息2"],
              "content_type": "内容类型",
              "visual_audio_consistency": "一致/有补充/不一致",
              "importance_score": 0-10分
            }
            """, segment.getAudioText());
        
        String response = visionClient.analyze(segment.getFrame().getImageData(), prompt);
        
        return SegmentAnalysis.builder()
            .segment(segment)
            .analysis(parseSegmentAnalysis(response))
            .build();
    }
}

视频内容结构化输出

分析完之后，需要生成结构化的内容报告：

@Component
public class VideoContentSummarizer {
    
    @Autowired
    private LlmClient llmClient;
    
    /**
     * 生成视频内容的多层次输出
     */
    public VideoContentReport generateReport(AlignedAnalysisResult analysisResult,
                                               VideoMetadata metadata) {
        
        // 收集所有段落分析
        List<SegmentAnalysis> analyses = analysisResult.getSegmentAnalyses();
        
        // 一句话摘要
        String oneSentenceSummary = generateOneSentenceSummary(analyses);
        
        // 内容大纲（保留时间戳）
        List<ChapterOutline> outline = generateOutline(analyses);
        
        // 关键帧截图（信息量最高的帧）
        List<VideoFrame> thumbnails = selectThumbnails(analyses);
        
        // 提取的关键数据（如果视频涉及数字/统计）
        List<KeyDataPoint> keyData = extractKeyData(analyses);
        
        // 内容标签
        List<String> tags = generateTags(analyses, analysisResult.getFullTranscript());
        
        return VideoContentReport.builder()
            .videoId(metadata.getVideoId())
            .duration(metadata.getDurationSeconds())
            .oneSentenceSummary(oneSentenceSummary)
            .outline(outline)
            .keyThumbnails(thumbnails)
            .keyDataPoints(keyData)
            .tags(tags)
            .fullTranscript(analysisResult.getFullTranscript())
            .processingDuration(analysisResult.getProcessingMs())
            .build();
    }
    
    /**
     * 生成带时间戳的内容大纲
     */
    private List<ChapterOutline> generateOutline(List<SegmentAnalysis> analyses) {
        // 把段落分析汇聚成章节
        String allSegments = analyses.stream()
            .map(a -> String.format("[%s] %s", 
                formatTime(a.getSegment().getStartTime()),
                a.getAnalysis().getContentSummary()))
            .collect(Collectors.joining("\n"));
        
        String prompt = String.format("""
            以下是视频按时间顺序的内容分析（每行格式：[时间戳] 内容摘要）：
            
            %s
            
            请将相关内容合并，生成视频的内容大纲，格式如下：
            - 每个主题章节一行
            - 标注开始时间戳
            - 章节标题简洁清晰（15字以内）
            
            返回JSON数组：
            [
              {
                "chapter_number": 1,
                "title": "章节标题",
                "start_time": "00:00",
                "end_time": "02:30",
                "summary": "该章节内容摘要（50字以内）"
              }
            ]
            """, allSegments);
        
        return parseChapterOutline(llmClient.complete(prompt));
    }
    
    /**
     * 格式化时间戳
     */
    private String formatTime(double seconds) {
        int mins = (int)(seconds / 60);
        int secs = (int)(seconds % 60);
        return String.format("%02d:%02d", mins, secs);
    }
    
    /**
     * 从视频中提取关键数字/统计数据
     * 对于包含数据展示的业务视频，这个功能很有价值
     */
    private List<KeyDataPoint> extractKeyData(List<SegmentAnalysis> analyses) {
        List<String> keyInfoList = analyses.stream()
            .flatMap(a -> a.getAnalysis().getKeyInformation().stream())
            .collect(Collectors.toList());
        
        if (keyInfoList.isEmpty()) return Collections.emptyList();
        
        String keyInfoText = String.join("\n", keyInfoList);
        
        String prompt = String.format("""
            从以下视频内容要点中提取具体的数据点（数字、比例、排名等）：
            
            %s
            
            返回JSON数组（只包含有明确数字的内容）：
            [
              {
                "metric_name": "指标名称",
                "value": "数值（含单位）",
                "context": "数据的背景说明",
                "timestamp": "大约在视频的哪个位置（如果知道）"
              }
            ]
            如果没有明确数据，返回空数组[]。
            """, keyInfoText);
        
        return parseKeyDataPoints(llmClient.complete(prompt));
    }
}

视频检索的实际应用

做好了视频分析，就可以支持视频内容搜索：

@Service
public class VideoSearchService {
    
    @Autowired
    private EmbeddingService embeddingService;
    
    @Autowired
    private VectorDatabase vectorDatabase;
    
    /**
     * 视频入库：分析 + 向量化 + 存储
     */
    public void indexVideo(String videoPath, VideoMetadata metadata) {
        
        // 分析
        AlignedAnalysisResult analysis = analyzer.analyze(videoPath);
        VideoContentReport report = summarizer.generateReport(analysis, metadata);
        
        // 将各层次内容向量化
        List<VideoSearchEntry> entries = new ArrayList<>();
        
        // 整体摘要的向量
        float[] summaryVector = embeddingService.embed(report.getOneSentenceSummary());
        entries.add(VideoSearchEntry.builder()
            .videoId(metadata.getVideoId())
            .entryType("SUMMARY")
            .text(report.getOneSentenceSummary())
            .vector(summaryVector)
            .timestamp(0.0)
            .build());
        
        // 每个章节的向量（支持章节级搜索）
        for (ChapterOutline chapter : report.getOutline()) {
            float[] chapterVector = embeddingService.embed(
                chapter.getTitle() + " " + chapter.getSummary());
            
            entries.add(VideoSearchEntry.builder()
                .videoId(metadata.getVideoId())
                .entryType("CHAPTER")
                .text(chapter.getTitle() + ": " + chapter.getSummary())
                .vector(chapterVector)
                .timestamp(parseTime(chapter.getStartTime()))
                .chapterTitle(chapter.getTitle())
                .build());
        }
        
        // 全文转录的分块向量（支持语句级搜索）
        List<String> transcriptChunks = chunkTranscript(report.getFullTranscript(), 200);
        for (int i = 0; i < transcriptChunks.size(); i++) {
            String chunk = transcriptChunks.get(i);
            float[] chunkVector = embeddingService.embed(chunk);
            
            entries.add(VideoSearchEntry.builder()
                .videoId(metadata.getVideoId())
                .entryType("TRANSCRIPT_CHUNK")
                .text(chunk)
                .vector(chunkVector)
                .chunkIndex(i)
                .build());
        }
        
        // 批量存入向量数据库
        vectorDatabase.batchInsert(entries);
    }
    
    /**
     * 视频搜索：返回相关视频及具体时间点
     */
    public List<VideoSearchResult> search(String query, int topK) {
        float[] queryVector = embeddingService.embed(query);
        
        // 向量搜索
        List<VideoSearchEntry> matches = vectorDatabase.search(queryVector, topK * 3);
        
        // 按视频聚合，并取每个视频的最高分
        Map<String, VideoSearchResult> resultMap = new LinkedHashMap<>();
        
        for (VideoSearchEntry match : matches) {
            String videoId = match.getVideoId();
            
            if (!resultMap.containsKey(videoId)) {
                resultMap.put(videoId, VideoSearchResult.builder()
                    .videoId(videoId)
                    .matchedEntries(new ArrayList<>())
                    .build());
            }
            
            resultMap.get(videoId).getMatchedEntries().add(match);
        }
        
        // 排序并取top K
        return resultMap.values().stream()
            .sorted(Comparator.comparingDouble(r -> 
                -r.getMatchedEntries().get(0).getScore()))
            .limit(topK)
            .collect(Collectors.toList());
    }
}

长视频的分治处理

对于超过30分钟的长视频（培训视频、会议录像），需要用分治策略：

@Component
public class LongVideoProcessor {
    
    private static final int SEGMENT_DURATION_MINUTES = 10;
    
    @Autowired
    private AudioVideoAlignedAnalyzer segmentAnalyzer;
    
    /**
     * 长视频分段处理 + 汇聚
     */
    public VideoContentReport processLongVideo(String videoPath, VideoMetadata metadata) {
        
        double totalDurationSeconds = getVideoDuration(videoPath);
        int segmentCount = (int)Math.ceil(totalDurationSeconds / (SEGMENT_DURATION_MINUTES * 60));
        
        log.info("视频时长{}秒，分{}段处理", totalDurationSeconds, segmentCount);
        
        // 切分视频（或用时间段参数，不实际切文件）
        List<VideoSegmentInfo> segments = buildSegments(totalDurationSeconds, segmentCount);
        
        // 并行处理各段
        List<CompletableFuture<SegmentReport>> futures = segments.stream()
            .map(seg -> CompletableFuture.supplyAsync(() -> {
                return processSegment(videoPath, seg);
            }, videoProcessingPool))
            .collect(Collectors.toList());
        
        // 等待所有段处理完成
        List<SegmentReport> segmentReports = futures.stream()
            .map(CompletableFuture::join)
            .sorted(Comparator.comparingDouble(r -> r.getSegment().getStartSeconds()))
            .collect(Collectors.toList());
        
        // 汇聚各段报告
        return aggregateSegmentReports(segmentReports, metadata);
    }
    
    private SegmentReport processSegment(String videoPath, VideoSegmentInfo segment) {
        // 提取这段的帧和音频
        List<VideoFrame> frames = frameExtractor.extractFrames(videoPath, 
            segment.getStartSeconds(), segment.getEndSeconds());
        byte[] audioData = audioExtractor.extractAudio(videoPath,
            segment.getStartSeconds(), segment.getEndSeconds());
        
        // 分析
        return segmentAnalyzer.analyze(frames, audioData, segment);
    }
    
    /**
     * 汇聚各段报告：生成整体大纲和摘要
     */
    private VideoContentReport aggregateSegmentReports(List<SegmentReport> reports,
                                                         VideoMetadata metadata) {
        // 收集所有章节
        List<ChapterOutline> allChapters = reports.stream()
            .flatMap(r -> r.getChapters().stream())
            .collect(Collectors.toList());
        
        // 调整时间偏移（每段的时间戳要加上对应的起始偏移量）
        adjustTimeOffsets(allChapters, reports);
        
        // 合并全文转录
        String fullTranscript = reports.stream()
            .map(SegmentReport::getTranscript)
            .collect(Collectors.joining(" "));
        
        // 生成整体摘要（基于各段摘要，而非重新分析全文）
        String overallSummary = generateOverallSummary(reports);
        
        return VideoContentReport.builder()
            .videoId(metadata.getVideoId())
            .duration(metadata.getDurationSeconds())
            .oneSentenceSummary(overallSummary)
            .outline(allChapters)
            .fullTranscript(fullTranscript)
            .build();
    }
    
    /**
     * 基于各段摘要生成整体摘要
     * 注意：不要发全文给LLM，用各段摘要就够了
     */
    private String generateOverallSummary(List<SegmentReport> reports) {
        String segmentSummaries = IntStream.range(0, reports.size())
            .mapToObj(i -> String.format("第%d段（%s-%s）：%s", 
                i + 1,
                formatTime(reports.get(i).getSegment().getStartSeconds()),
                formatTime(reports.get(i).getSegment().getEndSeconds()),
                reports.get(i).getSummary()))
            .collect(Collectors.joining("\n"));
        
        String prompt = String.format("""
            以下是一个长视频按时间顺序各段的内容摘要：
            
            %s
            
            请综合以上内容，生成这个视频的整体摘要：
            1. 一句话总结（20字以内，作为标题）
            2. 详细摘要（200字以内，说明视频的主要内容和结构）
            3. 核心观点/结论（3-5条）
            
            返回JSON格式：
            {
              "title": "标题",
              "summary": "详细摘要",
              "key_takeaways": ["要点1", "要点2", ...]
            }
            """, segmentSummaries);
        
        return llmClient.complete(prompt);
    }
}

踩坑实录

坑1：PyAV vs FFmpegFrameGrabber性能差异

Java里用JavaCV的FFmpegFrameGrabber处理大视频时，内存占用高且有时候帧时间戳不准确。后来改用命令行调用FFmpeg提取帧，稳定多了：

// 用FFmpeg命令提取关键帧（场景切换检测）
private void extractFramesWithFFmpeg(String videoPath, String outputDir) {
    ProcessBuilder pb = new ProcessBuilder(
        "ffmpeg", "-i", videoPath,
        "-vf", "select=gt(scene\\,0.4)",  // 场景切换阈值
        "-vsync", "vfr",
        "-q:v", "2",
        outputDir + "/frame_%04d.jpg"
    );
    pb.redirectErrorStream(true);
    // ...执行并等待完成
}

坑2：帧图像质量压缩

传给VLM的帧图像，不需要高分辨率，720p已经足够。但如果视频里有文字（如PPT演示），分辨率太低会导致文字无法识别。要根据内容类型决定分辨率——如果检测到有文字内容，用1080p；纯画面用720p。

坑3：音视频时间戳不同步

有些视频文件的音视频时间戳有偏移，导致对齐出问题。要在预处理时检测并修复：

# 检测音视频偏移
ffprobe -v quiet -print_format json -show_streams video.mp4 | jq '.streams[] | {codec_type, start_time}'

坑4：语言切换视频

有些会议视频里中英文混说，甚至切换到其他语言。Whisper虽然支持多语言，但在单视频内语言切换时，要设置language=null让它自动检测，而不是固定设zh。

成本控制很重要

一分钟视频，如果每秒采一帧，就是60帧要分析。GPT-4V一次分析1帧大概花0.01-0.02美元，60帧就是0.6-1.2美元。一部2小时电影，那成本就爆炸了。

我们的成本控制策略：

场景切换才采样，平均每分钟3-5帧，而不是每秒
低信息量帧（黑屏、转场）直接过滤
相似帧去重（相邻帧差异<5%不采样）
音频转录给整体语义，视觉分析给关键帧细节

这样下来，2小时视频的分析成本控制在5-10美元，是可接受的。

小结

视频内容理解，关键工程挑战集中在：

帧采样策略：场景切换检测 > 均匀采样，这是质量的基础
音视频对齐：音频文字 + 视觉内容结合，理解更全面
长视频分治：不要试图一次处理，分段 + 汇聚
成本控制：帧过滤 + 缓存，按信息量采样
结构化输出：不只输出文字，时间戳大纲更有价值

视频理解是一个成熟度还在快速提升的领域，现在这些方案还比较工程化，相信未来会有更原生的解法。