Label Studio 视频分类标注模板实战指南Video / HyperText 双方案与数据准备【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 是一套多类型数据标注工具其视频分类模板用于为内容审核、运动分析、安防监控、医学视频分析等场景构建分类数据集。本文基于仓库中的官方模板文档docs/source/templates/video_classification.md完整讲解基于 Video 标签与 HyperText 标签的两种标注配置写法、输入数据组织方式并结合前端编辑器源码web/libs/editor/src/tags/object/Video/Video.js与真实模板实现label_studio/annotation_templates/videos/video-classification/config.xml深化说明底层原理与视频格式要求。读完本文你将能够独立编写、调试并落地一套可运行的视频分类标注配置。模板定位与应用场景视频分类是视频理解任务中最基础的形态给定一段视频标注员判断其整体类别。模板文档明确指出其典型用途包括内容审核content moderation与模型训练数据准备。仓库中该模板的元数据label_studio/annotation_templates/videos/video-classification/config.yml进一步列举了适用的行业场景体育分析、医学视频分析、安防监控录像审查、娱乐行业、教育内容、质量控制、社交媒体内容过滤、广播媒体、安全监控、自动驾驶、无人机影像分析等并给出了与之配套的常见模型族3D CNN、I3D、SlowFast、TSN、TimeSformer、Video Transformer领域术语为动作识别action recognition、时序建模temporal modeling、视频理解video understanding等。该模板在 Label Studio 中提供了两套实现路径Video 标签方案使用原生Video对象标签直接播放视频文件配合Choices做类别选择这是官方推荐的主流方式HyperText 标签方案使用HyperText标签渲染一段包含video或embed的 HTML 片段来呈现视频适合嵌入外部视频如 YouTube或对既有 HTML 内容做二次标注的场景。下文分别展开。方案一使用 Video 标签进行视频分类完整标注配置模板文档给出的基于 Video 标签的配置如下View Video namevideo value$video/ Choices namechoice toNamevideo showInlinetrue Choice valueBlurry / Choice valueSharp / /Choices /View仓库中真实模板label_studio/annotation_templates/videos/video-classification/config.xml与本配置几乎一致仅将showInline写作showInLine两者在配置解析中等价其内置的演示数据指向仓库静态样例视频/static/samples/opossum_snow.mp4并附带了预填预测结果的示例可作为复制测试的参照。各标签角色拆解所有标注配置都必须包裹在View标签内View是标注界面的布局容器详见 docs/source/tags/view.md。Video是对象标签负责把视频片段渲染到标注界面该标签的完整参考见 docs/source/tags/video.mdVideo namevideo value$video/name元素名称是后续控制标签如Choices通过toName关联的目标value视频的 URL通常引用任务数据字段如$video。Choices是控制标签为标注员提供分类选项完整参数参考见 docs/source/includes/tags/choices.mdChoices namechoice toNamevideo showInlinetrue Choice valueBlurry / Choice valueSharp / /Choicesname选项组名称toName指向被标注的对象标签名此处为video建立控制-对象绑定showInlinetrue让选项与视频在同一行内紧凑显示每个Choice value...定义一个可选类别。Choices 参数深度说明从 docs/source/includes/tags/choices.md 可知Choices支持以下关键参数在视频分类场景中常用的有参数类型默认值说明namestring—选项组名称toNamestring—要标注的数据项名称choicesingle/single-radio/multiplesingle单选或多选分类showInlinebooleanfalse选项是否与对象同行显示requiredbooleanfalse是否校验必须作出选择requiredMessagestring—校验失败时展示的提示信息layoutselect/inline/verticalvertical下拉框、横向单行或纵向堆叠布局randomizebooleanfalse每次打开任务随机打乱选项顺序降低位置偏差perRegionboolean—对区域内结果而非整任务做选择perItemboolean—对对象内部某个 item 而非整个对象做选择visibleWhenregion-selected等—按区域/选择状态控制选项可见性valuestring—从任务数据动态加载选项列表视频分类通常保持默认的single单选语义若类别可多选如模糊与抖动同时成立可改为choicemultiple。此外Choices还支持通过value$字段名从任务数据动态加载选项适用于类别集合需要随任务变化的高级场景。Video 标签的底层实现在前端编辑器中Video标签由 web/libs/editor/src/tags/object/Video/Video.js 定义模型层与 web/libs/editor/src/tags/object/Video/HtxVideo.jsx 实现视图层。其 MST 属性模型TagAttrs与文档参数表一一对应参数类型默认值说明文档源码实现要点namestring—元素名称types.model的name属性valuestring—视频 URLvalue: types.maybeNull(types.string)取任务数据$videoframeRatenumber24每秒帧数可用$fps引用任务数据源码属性framerateafterCreate中会做归一化小于 1 的帧率会被转为1/framerate非法值回退为24syncstring—要同步的对象名由SyncableMixin驱动多对象同步播放mutedbooleanfalse静音播放视图层透传给VideoCanvas的muted属性heightnumber600播放器高度视图层直接作为容器高度style{{ height: Number(item.height) }}timelineHeightnumber64含区域的播放时间轴高度视图层传给Timeline height{...}defaultPlaybackSpeednumber1加载后的默认播放速度afterCreate中经上下界钳制后作为初始speedminPlaybackSpeednumber1允许的最低播放速度源码中实际下限为0.05默认兜底值0.25上限10且defaultPlaybackSpeed不得低于minPlaybackSpeed从源码可以看到几个值得注意的细节帧率归一化Video.jsafterCreateframeRate若小于 1会被解释为每帧秒数并取倒数非法或缺失时回退到 24。视频总时长 总帧数 / 帧率因此帧率设置直接影响时间轴与区域标注的帧定位精度。播放速度钳制源码对播放速度做了 [0.05, 10] 的硬性钳制并把默认最低速度兜底为 0.25这与文档参数表默认值略有差异文档写 1实际以源码为准。minPlaybackSpeed在视图层通过VideoConfigControl暴露给标注员调节。帧定位setFrame普通模式下通过currentTime frame / framerate跳转开启FF_VIDEO_FRAME_SEEK_PRECISION特性开关时使用逐帧精确跳转goToFrame。分类结果的合并模型层设置了mergeLabelsAndResults: true分类结果以独立choices类型 result 提交from_name指向choice、to_name指向video格式与下方标注结果示例一致。标注结果格式使用 Video 标签方案时一次Blurry分类的标注结果结构如下对应 label_studio/annotation_templates/videos/video-classification/config.xml 中的示例{ result: [ { value: { choices: [Blurry] }, id: vB3U85jSU4, from_name: choice, to_name: video, type: choices } ] }标注导出后即为标准化的 Label Studio 结果格式可直接用于下游模型训练。方案二使用 HyperText 标签进行视频分类当视频以 HTML 形式存在例如需要嵌入外部平台的视频可使用 HyperText 方案。模板文档给出的配置如下View Choices nametype toNamevideo choicesingle-radio Choice valueMotion/Choice Choice valueStable/Choice /Choices HyperText namevideo value$html/HyperText /View !-- { html: embed srchttps://www.youtube.com/embed/mf9TKj0NuTQ/embed } --该方案中Choices使用choicesingle-radio强制单选用单选框形式呈现关于single与single-radio的渲染差异见 docs/source/tags/choices.mdHyperText负责渲染 HTML 内容标签参考见 docs/source/tags/hypertext.mdHyperText namevideo value$html/HyperText输入数据组织使用 HyperText 方案时任务数据中的$html字段需要是一段可渲染的 HTML。模板文档给出两种形式。本地视频文件[ { html: video srcexamples.com/1.mp4 }, { html: video srcexamples.com/2.mp4 } ]嵌入网络视频[ { html: embed srchttps://www.youtube.com/embed/mf9TKj0NuTQ/embed } ]关于video标签的src属性用法模板文档建议参考 W3 Schools 的 HTML video 相关说明。需要注意HyperText 方案本质上是让浏览器渲染一段 HTML播放行为由浏览器原生控件接管Label Studio 无法精确感知视频帧号因此该方案适合整段视频打一个整体类别的粗粒度分类而需要逐帧标注区域、时间轴的任务应使用 Video 标签方案。视频数据格式与预处理关键前置条件Label Studio 依赖浏览器播放视频并据此评估总帧数因此视频编码格式的兼容性直接决定标注体验。文档与 docs/source/tags/video.md 均强调推荐使用 MP4 容器 H.264 (AVC) 视频编码 AAC 音频编码这是现代浏览器普遍支持的组合可避免总时长检测错误与播放异常。同时建议将视频转换为恒定帧率CFR理想值为 30 fps以避免帧数偏差、重复帧或丢帧且文件内的音频流与视频流时长必须一致否则会出现多余的总帧数。使用 FFmpeg 转码为标准格式文档提供了完整的 FFmpeg 转码命令第一步先用 ffprobe 提取视频流精确时长# Extract the exact video stream duration in seconds DUR$(ffprobe -v error -select_streams v:0 -show_entries streamduration -of defaultnokey1:noprint_wrappers1 input.mp4) # Re-encode media file to recommended format ffmpeg -i input_video.mp4 -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p -r 30 -c:a aac -b:a 128k -to $DUR output_video.mp4各参数含义参数作用-i input_video.mp4指定源视频-c:v libx264使用 H.264 编码器-profile:v high -level 4.0设置广泛设备兼容的 profile/level-pix_fmt yuv420p保证像素格式被多数浏览器支持-r 30强制恒定 30 fps若 100% 确认源视频已是恒定帧率可省略该参数FFmpeg 会保留原帧率-c:a aac -b:a 128k音频编码为 AAC、码率 128 kbps-to $DUR容器时钟到达视频结束时间戳即停止写入自动丢弃多余的音频尾部output_video.mp4转换后的输出文件可直接用于 Label Studio该转码流程同样以 JSDoc 注释形式内嵌于前端源码web/libs/editor/src/tags/object/Video/Video.js与官方文档保持一致可见这是官方认可的标准化预处理路径。检查视频参数转码前后建议用 ffprobe 全量检查视频的格式、流与时长信息ffprobe -v error -show_format -show_streams -print_format json input.mp4重点核对容器格式是否为 MP4、视频编码是否为 H.264、是否有恒定帧率、音频流与视频流时长是否一致。进阶扩展从分类走向更丰富的视频标注视频分类模板是视频标注能力的入口。基于同一个Video标签仓库还提供了可组合的扩展方向帧级分类模板集 label_studio/annotation_templates/videos/video-frame-classification/config.yml 展示了对特定帧做分类的配置写法视频转写将Choices换成TextArea即可实现视频内容转写示例见 docs/source/tags/video.mdView Video namevideo value$video / TextArea nameta toNamevideo / /View目标跟踪与时间轴分割模板集 label_studio/annotation_templates/videos/video-object-tracking/config.yml 与 label_studio/annotation_templates/videos/video-timeline-segmentation/config.xml 分别覆盖跨帧目标跟踪与时间轴区域分割均以Video标签为底座其区域/时间轴能力在 HtxVideo.jsx 中由Timeline组件与区域叠加层提供。自定义播放控制如需精细控制播放速度可配置defaultPlaybackSpeed与minPlaybackSpeed例如View Video namevideo value$video defaultPlaybackSpeed2 minPlaybackSpeed1.5 / /View这对需要慢速逐帧审视的视频分类如动作细节判定尤为实用。相关标签速查标签作用文档Video播放视频的对象标签docs/source/tags/video.mdHyperText渲染 HTML可内嵌视频的对象标签docs/source/tags/hypertext.mdChoices单选/多选分类控制标签docs/source/tags/choices.md小结本文围绕 docs/source/templates/video_classification.md 的官方模板完整覆盖了两套视频分类配置方案Video 标签方案适合标准视频文件且支持逐帧标注能力HyperText 标签方案适合 HTML 嵌入或外部平台视频的粗粒度分类并给出了参数表、标注结果格式、FFmpeg 转码命令与视频格式要求。落地时建议先按MP4 H.264/AAC 恒定 30fps完成视频预处理再基于VideoChoices的组合创建标注项目即可快速产出标准化的视频分类训练数据集。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考