TJC.Cyclops.VideoKit 2025.12.3.3

Cyclops.VideoKit

项目概述

Cyclops.VideoKit是Cyclops.Framework框架中的视频处理组件，提供全面的视频处理功能，包括视频编码解码、格式转换、剪辑、特效添加、缩略图生成和流媒体支持。该组件简化了视频相关应用开发，支持多种视频格式，提供高性能的处理能力，适用于视频编辑、内容管理、直播应用和媒体处理系统。

核心功能模块

视频编码与解码

• 多格式视频编码
• 硬件加速支持
• 质量与性能平衡控制
• 自定义编解码器配置

视频处理

• 视频格式转换
• 分辨率调整
• 帧率控制
• 视频裁剪与拼接

视频特效

• 滤镜应用
• 水印添加
• 转场效果
• 动画效果

媒体分析

• 视频元数据提取
• 关键帧检测
• 内容分析
• 质量评估

流媒体支持

• HLS流媒体生成
• DASH支持
• 流媒体服务器集成
• 自适应比特率流

高级功能

• 实时视频处理
• 批量处理工具
• 视频压缩优化
• 3D视频支持

技术栈

• .NET 8.0
• FFmpeg (包装与集成)
• MediaInfo
• Cyclops.Common
• Cyclops.Storage

环境依赖

• .NET 8.0 SDK
• FFmpeg (需要单独安装，版本建议4.0+)
• 可选：NVIDIA CUDA (用于硬件加速)

安装配置

NuGet安装

Install-Package Cyclops.VideoKit

基本配置

在应用程序启动时进行配置：

// 在Program.cs或Startup.cs中
using Cyclops.VideoKit;

var builder = WebApplication.CreateBuilder(args);

// 添加Cyclops.VideoKit服务
builder.Services.AddCyclopsVideoKit(options => {
    // FFmpeg路径配置
    options.FfmpegPath = @"C:\ffmpeg\bin\ffmpeg.exe";
    options.FfprobePath = @"C:\ffmpeg\bin\ffprobe.exe";
    
    // 编码配置
    options.EncodingOptions = new VideoEncodingOptions {
        DefaultVideoCodec = "h264",
        DefaultAudioCodec = "aac",
        DefaultPreset = "medium", // 编码预设：ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
        EnableHardwareAcceleration = true
    };
    
    // 临时文件配置
    options.TempFileOptions = new TempFileOptions {
        TempDirectory = Path.GetTempPath(),
        AutoCleanup = true,
        MaxTempFileAge = TimeSpan.FromHours(24)
    };
});

// ...

代码示例

视频转换示例

using Cyclops.VideoKit.Services;
using Microsoft.Extensions.DependencyInjection;

public class VideoConversionService
{
    private readonly IVideoConverter _videoConverter;
    private readonly IVideoAnalyzer _videoAnalyzer;
    
    public VideoConversionService(IVideoConverter videoConverter, IVideoAnalyzer videoAnalyzer)
    {
        _videoConverter = videoConverter;
        _videoAnalyzer = videoAnalyzer;
    }
    
    public async Task<VideoConversionResult> ConvertVideoAsync(string sourceFilePath, string outputFilePath, VideoConversionOptions options)
    {
        try
        {
            // 分析源视频信息
            var sourceInfo = await _videoAnalyzer.GetVideoInfoAsync(sourceFilePath);
            Console.WriteLine($"源视频信息: {sourceInfo.Format}，分辨率: {sourceInfo.Width}x{sourceInfo.Height}，时长: {sourceInfo.Duration.TotalSeconds}秒");
            
            // 配置转换选项
            var conversionOptions = new VideoConversionOptions {
                OutputFormat = options.OutputFormat ?? "mp4",
                VideoCodec = options.VideoCodec ?? "h264",
                VideoBitrate = options.VideoBitrate ?? "2M", // 2Mbps
                AudioCodec = options.AudioCodec ?? "aac",
                AudioBitrate = options.AudioBitrate ?? "128k",
                Width = options.Width, // 可选，不指定则保持原始宽度
                Height = options.Height, // 可选，不指定则保持原始高度
                PreserveAspectRatio = options.PreserveAspectRatio ?? true,
                EnableHardwareAcceleration = options.EnableHardwareAcceleration ?? true
            };
            
            // 显示转换配置
            Console.WriteLine($"开始转换视频: {Path.GetFileName(sourceFilePath)} -> {Path.GetFileName(outputFilePath)}");
            Console.WriteLine($"输出格式: {conversionOptions.OutputFormat}");
            Console.WriteLine($"视频编码: {conversionOptions.VideoCodec} @ {conversionOptions.VideoBitrate}");
            Console.WriteLine($"音频编码: {conversionOptions.AudioCodec} @ {conversionOptions.AudioBitrate}");
            
            // 执行转换
            var result = await _videoConverter.ConvertAsync(sourceFilePath, outputFilePath, conversionOptions, 
                progressCallback: (progress) => {
                    Console.WriteLine($"转换进度: {progress.Percentage:P2}, 速度: {progress.Speed}x");
                });
            
            // 分析转换后的视频
            var outputInfo = await _videoAnalyzer.GetVideoInfoAsync(outputFilePath);
            
            Console.WriteLine($"转换完成!");
            Console.WriteLine($"输出视频信息: {outputInfo.Format}，分辨率: {outputInfo.Width}x{outputInfo.Height}，时长: {outputInfo.Duration.TotalSeconds}秒，文件大小: {new FileInfo(outputFilePath).Length / 1024 / 1024:F2}MB");
            
            return new VideoConversionResult {
                Success = true,
                OutputPath = outputFilePath,
                OutputInfo = outputInfo,
                ProcessingTime = result.ProcessingTime,
                OriginalSize = result.OriginalSize,
                OutputSize = result.OutputSize,
                CompressionRatio = result.CompressionRatio
            };
        }
        catch (Exception ex)
        {
            Console.WriteLine($"转换失败: {ex.Message}");
            throw;
        }
    }
    
    // 批量转换示例
    public async Task<IEnumerable<VideoConversionResult>> BatchConvertVideosAsync(IEnumerable<VideoConversionJob> jobs)
    {
        var results = new List<VideoConversionResult>();
        
        foreach (var job in jobs)
        {
            var result = await ConvertVideoAsync(job.SourceFilePath, job.OutputFilePath, job.Options);
            results.Add(result);
        }
        
        return results;
    }
}

// 视频转换选项
public class VideoConversionOptions
{
    public string OutputFormat { get; set; }
    public string VideoCodec { get; set; }
    public string VideoBitrate { get; set; }
    public string AudioCodec { get; set; }
    public string AudioBitrate { get; set; }
    public int? Width { get; set; }
    public int? Height { get; set; }
    public bool? PreserveAspectRatio { get; set; }
    public bool? EnableHardwareAcceleration { get; set; }
}

public class VideoConversionJob
{
    public string SourceFilePath { get; set; }
    public string OutputFilePath { get; set; }
    public VideoConversionOptions Options { get; set; }
}

public class VideoConversionResult
{
    public bool Success { get; set; }
    public string OutputPath { get; set; }
    public VideoInfo OutputInfo { get; set; }
    public TimeSpan ProcessingTime { get; set; }
    public long OriginalSize { get; set; }
    public long OutputSize { get; set; }
    public double CompressionRatio { get; set; }
}

// 视频信息模型
public class VideoInfo
{
    public string Format { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }
    public TimeSpan Duration { get; set; }
    public double Framerate { get; set; }
    public string VideoCodec { get; set; }
    public string AudioCodec { get; set; }
    public int AudioChannels { get; set; }
    public int SampleRate { get; set; }
}

视频编辑与特效示例

using Cyclops.VideoKit.Editing;
using Microsoft.Extensions.DependencyInjection;

// 视频剪辑服务
public class VideoEditingService
{
    private readonly IVideoEditor _videoEditor;
    
    public VideoEditingService(IVideoEditorFactory videoEditorFactory)
    {
        _videoEditor = videoEditorFactory.Create();
    }
    
    // 视频裁剪
    public async Task<string> TrimVideoAsync(string sourcePath, TimeSpan startTime, TimeSpan endTime, string outputPath)
    {
        Console.WriteLine($"开始裁剪视频: {Path.GetFileName(sourcePath)}，从 {startTime} 到 {endTime}");
        
        try
        {
            // 执行裁剪
            await _videoEditor.TrimAsync(sourcePath, startTime, endTime, outputPath);
            Console.WriteLine($"视频裁剪完成: {Path.GetFileName(outputPath)}");
            return outputPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"视频裁剪失败: {ex.Message}");
            throw;
        }
    }
    
    // 视频合并
    public async Task<string> MergeVideosAsync(IEnumerable<string> videoPaths, string outputPath)
    {
        Console.WriteLine($"开始合并 {videoPaths.Count()} 个视频片段");
        
        try
        {
            // 创建合并列表文件
            var listFilePath = Path.Combine(Path.GetTempPath(), $"merge_list_{Guid.NewGuid()}.txt");
            
            using (var writer = new StreamWriter(listFilePath))
            {
                foreach (var videoPath in videoPaths)
                {
                    writer.WriteLine($"file '{videoPath}'");
                }
            }
            
            // 执行合并
            await _videoEditor.MergeAsync(listFilePath, outputPath);
            
            // 删除临时列表文件
            File.Delete(listFilePath);
            
            Console.WriteLine($"视频合并完成: {Path.GetFileName(outputPath)}");
            return outputPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"视频合并失败: {ex.Message}");
            throw;
        }
    }
    
    // 添加水印
    public async Task<string> AddWatermarkAsync(string videoPath, string watermarkPath, string outputPath, 
        WatermarkPosition position = WatermarkPosition.BottomRight, double opacity = 0.5)
    {
        Console.WriteLine($"开始添加水印到视频: {Path.GetFileName(videoPath)}");
        
        try
        {
            // 配置水印选项
            var watermarkOptions = new WatermarkOptions {
                WatermarkPath = watermarkPath,
                Position = position,
                Opacity = opacity,
                Margin = 20 // 边距，像素
            };
            
            // 添加水印
            await _videoEditor.AddWatermarkAsync(videoPath, watermarkOptions, outputPath);
            
            Console.WriteLine($"水印添加完成: {Path.GetFileName(outputPath)}");
            return outputPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"添加水印失败: {ex.Message}");
            throw;
        }
    }
}

// 水印位置枚举
public enum WatermarkPosition
{
    TopLeft,
    TopRight,
    BottomLeft,
    BottomRight,
    Center
}

// 水印选项
public class WatermarkOptions
{
    public string WatermarkPath { get; set; }
    public WatermarkPosition Position { get; set; }
    public double Opacity { get; set; }
    public int Margin { get; set; }
    public int? Width { get; set; } // 可选，指定水印宽度
    public int? Height { get; set; } // 可选，指定水印高度
}

// 视频滤镜示例
public class VideoFilterService
{
    private readonly IVideoFilter _videoFilter;
    
    public VideoFilterService(IVideoFilterFactory filterFactory)
    {
        _videoFilter = filterFactory.Create();
    }
    
    // 应用视频滤镜
    public async Task<string> ApplyFiltersAsync(string sourcePath, string outputPath, params FilterType[] filters)
    {
        Console.WriteLine($"开始应用滤镜到视频: {Path.GetFileName(sourcePath)}");
        
        try
        {
            // 创建滤镜链
            var filterChain = new List<string>();
            
            foreach (var filter in filters)
            {
                switch (filter)
                {
                    case FilterType.Grayscale:
                        filterChain.Add("grayscale=1");
                        Console.WriteLine("添加灰度滤镜");
                        break;
                    case FilterType.Brightness:
                        filterChain.Add("eq=brightness=1.2"); // 增加20%亮度
                        Console.WriteLine("添加亮度滤镜");
                        break;
                    case FilterType.Contrast:
                        filterChain.Add("eq=contrast=1.3"); // 增加30%对比度
                        Console.WriteLine("添加对比度滤镜");
                        break;
                    case FilterType.Sharpen:
                        filterChain.Add("unsharp=5:5:0.5");
                        Console.WriteLine("添加锐化滤镜");
                        break;
                }
            }
            
            // 应用滤镜
            await _videoFilter.ApplyFiltersAsync(sourcePath, outputPath, filterChain, 
                progressCallback: (progress) => {
                    Console.WriteLine($"滤镜应用进度: {progress.Percentage:P2}");
                });
            
            Console.WriteLine($"滤镜应用完成: {Path.GetFileName(outputPath)}");
            return outputPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"应用滤镜失败: {ex.Message}");
            throw;
        }
    }
}

// 滤镜类型枚举
public enum FilterType
{
    Grayscale,
    Brightness,
    Contrast,
    Sharpen,
    Blur,
    Saturation
}

缩略图和流媒体示例

using Cyclops.VideoKit.Thumbnails;
using Cyclops.VideoKit.Streaming;
using Microsoft.Extensions.DependencyInjection;

// 视频缩略图服务
public class VideoThumbnailService
{
    private readonly IVideoThumbnailGenerator _thumbnailGenerator;
    
    public VideoThumbnailService(IVideoThumbnailGeneratorFactory thumbnailFactory)
    {
        _thumbnailGenerator = thumbnailFactory.Create();
    }
    
    // 生成单个缩略图
    public async Task<string> GenerateThumbnailAsync(string videoPath, TimeSpan timestamp, string outputPath, ThumbnailOptions options = null)
    {
        try
        {
            Console.WriteLine($"为视频生成缩略图: {Path.GetFileName(videoPath)}，时间点: {timestamp}");
            
            // 生成缩略图
            await _thumbnailGenerator.GenerateSingleAsync(videoPath, timestamp, outputPath, options);
            
            Console.WriteLine($"缩略图生成完成: {Path.GetFileName(outputPath)}");
            return outputPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"生成缩略图失败: {ex.Message}");
            throw;
        }
    }
    
    // 生成多个缩略图（时间轴缩略图）
    public async Task<IEnumerable<string>> GenerateThumbnailStripAsync(string videoPath, string outputDirectory, int count = 10)
    {
        var results = new List<string>();
        
        try
        {
            // 分析视频时长
            var analyzer = new VideoAnalyzer();
            var videoInfo = await analyzer.GetVideoInfoAsync(videoPath);
            
            // 计算缩略图时间间隔
            var interval = videoInfo.Duration.TotalSeconds / (count + 1);
            
            Console.WriteLine($"为视频生成时间轴缩略图: {Path.GetFileName(videoPath)}，共 {count} 个");
            
            // 生成多个缩略图
            for (int i = 1; i <= count; i++)
            {
                var timestamp = TimeSpan.FromSeconds(interval * i);
                var outputPath = Path.Combine(outputDirectory, $"thumbnail_{i:D3}.jpg");
                
                await _thumbnailGenerator.GenerateSingleAsync(videoPath, timestamp, outputPath, 
                    new ThumbnailOptions {
                        Width = 320, // 缩略图宽度
                        Height = 0, // 高度自动计算以保持比例
                        Quality = 85
                    });
                
                results.Add(outputPath);
            }
            
            return results;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"生成缩略图失败: {ex.Message}");
            throw;
        }
    }
}

// 缩略图选项
public class ThumbnailOptions
{
    public int Width { get; set; } = 320;
    public int Height { get; set; } = 0; // 0表示自动计算
    public int Quality { get; set; } = 80;
    public bool PreserveAspectRatio { get; set; } = true;
    public string Format { get; set; } = "jpg";
}

// 流媒体服务
public class StreamingService
{
    private readonly IHlsGenerator _hlsGenerator;
    
    public StreamingService(IHlsGeneratorFactory hlsFactory)
    {
        _hlsGenerator = hlsFactory.Create();
    }
    
    // 生成HLS流
    public async Task<string> CreateHlsStreamAsync(string videoPath, string outputDirectory, bool generateMultipleQualities = false)
    {
        try
        {
            Console.WriteLine($"开始生成HLS流: {Path.GetFileName(videoPath)}");
            
            // 配置HLS选项
            var hlsOptions = new HlsOptions {
                OutputDirectory = outputDirectory,
                SegmentDuration = TimeSpan.FromSeconds(10), // 每个片段10秒
                SegmentFilenamePattern = "segment_%03d.ts",
                PlaylistFilename = "playlist.m3u8",
                GenerateMultipleQualities = generateMultipleQualities,
                QualityLevels = generateMultipleQualities ? 
                    new[] {
                        new VideoQuality { Width = 640, Height = 360, VideoBitrate = "800k" }, // 360p
                        new VideoQuality { Width = 1280, Height = 720, VideoBitrate = "2M" }, // 720p
                        new VideoQuality { Width = 1920, Height = 1080, VideoBitrate = "5M" } // 1080p
                    } : 
                    null
            };
            
            // 生成HLS流
            await _hlsGenerator.GenerateHlsAsync(videoPath, hlsOptions, 
                progressCallback: (progress) => {
                    Console.WriteLine($"HLS生成进度: {progress.Percentage:P2}");
                });
            
            var masterPlaylistPath = Path.Combine(outputDirectory, hlsOptions.PlaylistFilename);
            Console.WriteLine($"HLS流生成完成: {masterPlaylistPath}");
            
            return masterPlaylistPath;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"HLS流生成失败: {ex.Message}");
            throw;
        }
    }
}

// 视频质量选项
public class VideoQuality
{
    public int Width { get; set; }
    public int Height { get; set; }
    public string VideoBitrate { get; set; }
    public string AudioBitrate { get; set; } = "128k";
}

// HLS选项
public class HlsOptions
{
    public string OutputDirectory { get; set; }
    public TimeSpan SegmentDuration { get; set; }
    public string SegmentFilenamePattern { get; set; }
    public string PlaylistFilename { get; set; }
    public bool GenerateMultipleQualities { get; set; }
    public VideoQuality[] QualityLevels { get; set; }
}

批量处理与高级功能

using Cyclops.VideoKit.Batch;
using Microsoft.Extensions.DependencyInjection;

// 批量视频处理服务
public class BatchVideoProcessor
{
    private readonly IBatchVideoProcessor _batchProcessor;
    private readonly IProgressTracker _progressTracker;
    
    public BatchVideoProcessor(IBatchVideoProcessorFactory batchProcessorFactory, IProgressTrackerFactory progressFactory)
    {
        _batchProcessor = batchProcessorFactory.Create();
        _progressTracker = progressFactory.Create("BatchVideoProcessing");
    }
    
    // 批量转换视频
    public async Task<BatchProcessingResult> ProcessVideoBatchAsync(IEnumerable<BatchVideoJob> jobs)
    {
        Console.WriteLine($"开始批量处理 {jobs.Count()} 个视频任务");
        
        // 设置进度回调
        _progressTracker.ProgressChanged += (sender, args) => {
            Console.WriteLine($"批处理进度: {args.Percentage:P2}, " +
                           $"已完成: {args.CompletedCount}/{args.TotalCount}, " +
                           $"当前: {args.CurrentItem}");
        };
        
        // 执行批量处理
        var result = await _batchProcessor.ProcessAsync(jobs.ToList(), _progressTracker, 
            maxParallelTasks: Environment.ProcessorCount); // 并行任务数设为CPU核心数
        
        Console.WriteLine($"批处理完成! 成功: {result.SuccessCount}, 失败: {result.FailureCount}");
        
        if (result.FailedJobs.Any())
        {
            Console.WriteLine("失败任务列表:");
            foreach (var failedJob in result.FailedJobs)
            {
                Console.WriteLine($"  - {failedJob.SourcePath}: {failedJob.ErrorMessage}");
            }
        }
        
        return result;
    }
}

// 批量处理作业
public class BatchVideoJob
{
    public string SourcePath { get; set; }
    public string OutputPath { get; set; }
    public VideoConversionOptions Options { get; set; }
}

// 批量处理结果
public class BatchProcessingResult
{
    public int TotalCount { get; set; }
    public int SuccessCount { get; set; }
    public int FailureCount { get; set; }
    public List<BatchVideoJob> SuccessfulJobs { get; set; }
    public List<FailedBatchJob> FailedJobs { get; set; }
}

public class FailedBatchJob
{
    public string SourcePath { get; set; }
    public string ErrorMessage { get; set; }
    public Exception Exception { get; set; }
}

// 视频压缩优化服务
public class VideoOptimizationService
{
    private readonly IVideoOptimizer _videoOptimizer;
    
    public VideoOptimizationService(IVideoOptimizerFactory optimizerFactory)
    {
        _videoOptimizer = optimizerFactory.Create();
    }
    
    public async Task<OptimizationResult> OptimizeVideoAsync(string videoPath, string outputPath, VideoOptimizationLevel level)
    {
        Console.WriteLine($"开始优化视频: {Path.GetFileName(videoPath)}, 优化级别: {level}");
        
        try
        {
            // 根据优化级别设置参数
            var optimizationOptions = new VideoOptimizationOptions {
                OptimizationLevel = level,
                TargetFileSize = level switch {
                    VideoOptimizationLevel.Low => 0, // 不指定目标大小，使用默认设置
                    VideoOptimizationLevel.Medium => 0,
                    VideoOptimizationLevel.High => 0,
                    VideoOptimizationLevel.Custom => 10 * 1024 * 1024, // 10MB
                    _ => 0
                },
                PreserveQuality = level != VideoOptimizationLevel.High,
                EnableTwoPassEncoding = true,
                RemoveAudio = false,
                MaxWidth = level == VideoOptimizationLevel.High ? 1280 : 0, // 高清优化限制宽度
            };
            
            // 执行优化
            var result = await _videoOptimizer.OptimizeAsync(videoPath, outputPath, optimizationOptions, 
                progressCallback: (progress) => {
                    Console.WriteLine($"优化进度: {progress.Percentage:P2}, 估计文件大小: {(progress.EstimatedOutputSize / 1024 / 1024):F2}MB");
                });
            
            Console.WriteLine($"视频优化完成: {Path.GetFileName(outputPath)}");
            Console.WriteLine($"原始大小: {(result.OriginalSize / 1024 / 1024):F2}MB");
            Console.WriteLine($"优化后大小: {(result.OptimizedSize / 1024 / 1024):F2}MB");
            Console.WriteLine($"压缩率: {result.CompressionRatio:P2}");
            
            return result;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"视频优化失败: {ex.Message}");
            throw;
        }
    }
}

// 优化级别
public enum VideoOptimizationLevel
{
    Low,    // 轻度优化，保持高质量
    Medium, // 平衡优化，中等质量
    High,   // 高度优化，压缩率优先
    Custom  // 自定义设置
}

// 优化结果
public class OptimizationResult
{
    public long OriginalSize { get; set; }
    public long OptimizedSize { get; set; }
    public double CompressionRatio { get; set; }
    public TimeSpan ProcessingTime { get; set; }
    public int OriginalBitrate { get; set; }
    public int OptimizedBitrate { get; set; }
}

// 优化选项
public class VideoOptimizationOptions
{
    public VideoOptimizationLevel OptimizationLevel { get; set; }
    public long TargetFileSize { get; set; } // 字节
    public bool PreserveQuality { get; set; }
    public bool EnableTwoPassEncoding { get; set; }
    public bool RemoveAudio { get; set; }
    public int MaxWidth { get; set; }
    public int MaxHeight { get; set; }
}

版本信息

• 当前版本
• 作者：yswenli
• 描述：企服版框架中视频处理组件

贡献者

• yswenli

许可证

保留所有权利