FluxMedia.Camera 0.1.0-alpha

FluxMedia

0.1.0-alpha 内测说明

当前包版本为 0.1.0-alpha，用于第一轮 NuGet 内测和真实环境验收，不是稳定正式版。建议先在测试项目或灰度环境验证 Playback、Camera、Recording 三个包的实际表现，再决定是否接入生产项目。

• 内测验收清单：docs/alpha-test-checklist.md
• 当前已知限制：docs/known-limitations.md

FluxMedia 是一套基于 C# 的多媒体框架，当前按三个可独立发布的 NuGet 功能包组织：

• FluxMedia.Playback：本地视频播放、网络拉流播放、播放器音频输出、播放控制和播放源录制。
• FluxMedia.Camera：USB 摄像头枚举、打开、预览、拍照和 USB 摄像头视频流录制。
• FluxMedia.Recording：屏幕采集、屏幕预览和屏幕录制。

三个功能包互不引用，只依赖 FluxMedia.Core。播放源录制属于 Playback，USB 摄像头录制属于 Camera，屏幕录制属于 Recording。

当前不包含：独立文本叠加轨能力、音频录入能力、系统输出声音采集、外部拾音设备采集、多路声音合成、媒体转封装/重新编码、按应用窗体采集或按应用窗体落盘。

FFmpeg Native 配置

FluxMedia 依赖 FFmpeg native library。推荐把 FFmpeg 文件放到以下任一位置：

• 程序运行目录。
• runtimes/{rid}/native，例如 runtimes/win-x64/native。
• 环境变量 FLUXMEDIA_FFMPEG_ROOT 指向的目录。
• 通过 NativeLibraryOptions.FFmpegRootDirectory 指定的目录。

Windows 下目录通常需要包含：

• avcodec-*.dll
• avformat-*.dll
• avutil-*.dll
• swscale-*.dll
• swresample-*.dll
• Camera 还需要 avdevice-*.dll
• 屏幕录制和部分录制能力需要 ffmpeg.exe

Sample 默认也会从程序目录、FFmpeg/x64、runtimes/{rid}/native 和 FLUXMEDIA_FFMPEG_ROOT 查找。

找不到 native library 时先看日志中的 NativeLibrary、FFmpegRootDirectory、SearchDirectory、LoadFailed、LastNativeError 字段。

FluxMedia.Playback 快速开始

本地文件播放：

await using var player = FluxPlayback.CreateSession();
await player.OpenAsync(new PlaybackOpenRequest(MediaSource.FromFile(@"D:\media\demo.mp4")));
await player.PlayAsync();

网络流播放：

await using var player = FluxPlayback.CreateSession();
await player.OpenUrlAsync("https://example.com/video.mp4");
await player.PlayAsync();

播放控制：

await player.SeekAsync(TimeSpan.FromSeconds(30));
await player.FastForwardAsync(TimeSpan.FromSeconds(10));
await player.RewindAsync(TimeSpan.FromSeconds(10));
await player.SetPlaybackRateAsync(1.5);
await player.SetVolumeAsync(0.6);
await player.SetMutedAsync(false);

播放源录制：

var recording = await player.CreateSourceRecordingAsync(
    new PlaybackSourceRecordingRequest(@"D:\output\playback-segment.mp4"));

await recording.StartAsync();
await Task.Delay(TimeSpan.FromSeconds(5));
await recording.StopAsync();
await recording.DisposeAsync();

音频输出说明：

• Playback 会解码媒体源中的音频流并输出到播放器音频设备。
• 音量和静音只影响播放器输出。
• Playback 不做音频录制、系统声音采集、麦克风采集或混音。
• Seek 后会重启音频 worker 并从目标时间继续，Sample 诊断区会显示音频时间、视频时间和音画差值。

FluxMedia.Camera 快速开始

枚举 USB 摄像头：

var enumerator = FluxCamera.CreateDeviceEnumerator();
var devices = await enumerator.EnumerateAsync();
var diagnostic = enumerator.GetDiagnosticInfo();

打开预览：

var device = devices.First();
await using var camera = FluxCamera.CreatePreviewSession(device);
camera.VideoFrameReady += (_, args) =>
{
    var frame = args.Frame;
};

await camera.OpenAsync();

拍照：

await camera.CaptureSnapshotAsync(
    new CameraSnapshotOptions(@"D:\output\camera.png"));

USB 摄像头视频流录制：

var recording = await camera.CreateRecordingAsync(
    new CameraRecordingOptions { OutputPath = @"D:\output\camera.mp4" });

await recording.StartAsync();
await Task.Delay(TimeSpan.FromSeconds(5));
await recording.StopAsync();
await recording.DisposeAsync();

真机验收重点：

• 无设备时枚举不崩溃，诊断显示 CameraDeviceCount=0。
• 设备被占用时 LastOpenFailureReason 应有明确原因。
• 停止预览或关闭页面后，其他软件应能重新打开摄像头。
• Sample USB 摄像头页会显示设备列表、当前设备、FFmpeg avdevice 状态、最近错误、拍照路径、录制路径和释放状态。

FluxMedia.Recording 快速开始

屏幕预览：

var enumerator = FluxRecording.CreateDisplayEnumerator();
var displays = await enumerator.EnumerateAsync();

await using var preview = FluxRecording.CreateScreenCapture(
    new ScreenCaptureOptions { Display = displays.First(), FrameRate = 15 });

preview.VideoFrameReady += (_, args) =>
{
    var frame = args.Frame;
};

await preview.StartAsync();

屏幕录制：

await using var recording = FluxRecording.CreateScreenRecording(
    new ScreenRecordingOptions
    {
        Display = displays.First(),
        OutputPath = @"D:\output\screen.mp4",
        FrameRate = 15
    });

await recording.StartAsync();
await Task.Delay(TimeSpan.FromSeconds(5));
await recording.StopAsync();

停止后验证：

• 输出 mp4 能被播放器打开。
• 输出文件能立即删除，说明没有文件占用。
• 日志中 OutputFileFinalized=True 或释放状态明确。

日志

日志默认写入：

Logs/yyyyMMdd.txt

日志格式包含时间、等级、模块名、SessionId / InstanceId、线程 ID、事件名和 Key=Value 参数，例如：

2026-06-04 19:20:01.123 [Info] [PlaybackSession] SessionId=... ThreadId=8 Event=Seek Target=00:00:30 SourceKind=File
2026-06-04 19:20:03.456 [Info] [CameraPreviewSession] SessionId=... ThreadId=10 Event=OpenCameraReady DeviceName=USB Camera
2026-06-04 19:20:05.789 [Info] [ScreenRecordingSession] SessionId=... ThreadId=12 Event=StopRecording Output=D:\screen.mp4 OutputSize=123456

常见排查入口：

• Playback 播放慢：看 OpenElapsed、StreamInfoElapsed、TimingMode、ReadPacketCount、DecodedFrameCount、PushedFrameCount。
• Playback 音画同步：看 AudioCurrentTime、VideoCurrentTime、AudioVideoDrift、AudioWorkerState。
• Playback 源录制时长：看 StartTime、StopTime、RecordedDuration、OutputFileDuration、StopCompleted。
• Camera 真机问题：看 RawDeviceCount、CameraDeviceCount、FFmpegAvDeviceAvailable、LastOpenFailureReason、LastReleaseState。
• Recording 文件损坏或占用：看 FFmpegProcessId、FFmpegExitCode、LastFFmpegError、OutputFileFinalized、OutputFileSize。

当前人工验收清单

Playback：

• 本地 MP4 播放有画面和声音。
• HTTP MP4 播放速度正常。
• Seek / 快进 / 快退后画面刷新到目标位置。
• 音频和视频同步，无明显漂移。
• 播放源录制只包含 Start 到 Stop 之间的片段。

Camera：

• Windows 真机能枚举 USB 摄像头。
• 能打开预览并持续刷新画面。
• 能拍照并生成 png。
• 能录制摄像头视频流并生成可播放 mp4。
• Stop / Dispose / 关闭窗口后摄像头资源释放，其他软件可重新打开。

Recording：

• 能枚举显示器。
• 屏幕预览有画面且 UI 不卡顿。
• 屏幕录制停止后 mp4 可播放。
• 停止后 mp4 可删除，没有文件占用。

构建验证

dotnet build FluxMedia.slnx
dotnet test FluxMedia.slnx --no-build
dotnet pack FluxMedia.slnx -c Release -o artifacts/packages