企业官网建设流程全解析

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-studio

Label 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 中提供了两套实现路径：

1. Video 标签方案：使用原生<Video>对象标签直接播放视频文件，配合<Choices>做类别选择，这是官方推荐的主流方式；
2. HyperText 标签方案：使用<HyperText>标签渲染一段包含<video>或<embed>的 HTML 片段来呈现视频，适合嵌入外部视频（如 YouTube）或对既有 HTML 内容做二次标注的场景。

下文分别展开。

方案一：使用 Video 标签进行视频分类

完整标注配置

模板文档给出的基于 Video 标签的配置如下：

<View> <Video name="video" value="$video"/> <Choices name="choice" toName="video" showInline="true"> <Choice value="Blurry" /> <Choice value="Sharp" /> </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.md）：

<Video name="video" value="$video"/>

• name：元素名称，是后续控制标签（如<Choices>）通过toName关联的目标；
• value：视频的 URL，通常引用任务数据字段，如$video。

<Choices>是控制标签，为标注员提供分类选项（完整参数参考见 docs/source/includes/tags/choices.md）：

<Choices name="choice" toName="video" showInline="true"> <Choice value="Blurry" /> <Choice value="Sharp" /> </Choices>

• name：选项组名称；
• toName：指向被标注的对象标签名（此处为video），建立"控制-对象"绑定；
• showInline="true"：让选项与视频在同一行内紧凑显示；
• 每个<Choice value="...">定义一个可选类别。

Choices 参数深度说明

从 docs/source/includes/tags/choices.md 可知<Choices>支持以下关键参数，在视频分类场景中常用的有：

视频分类通常保持默认的single（单选）语义；若类别可多选（如"模糊"与"抖动"同时成立），可改为choice="multiple"。此外<Choices>还支持通过value="$字段名"从任务数据动态加载选项，适用于类别集合需要随任务变化的高级场景。

Video 标签的底层实现

在前端编辑器中，<Video>标签由 web/libs/editor/src/tags/object/Video/Video.js 定义（模型层）与 web/libs/editor/src/tags/object/Video/HtxVideo.jsx 实现（视图层）。其 MST 属性模型（TagAttrs）与文档参数表一一对应：

从源码可以看到几个值得注意的细节：

• 帧率归一化（Video.jsafterCreate）：frameRate若小于 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 name="type" toName="video" choice="single-radio"> <Choice value="Motion"></Choice> <Choice value="Stable"></Choice> </Choices> <HyperText name="video" value="$html"></HyperText> </View> <!-- { "html": "<embed src='https://www.youtube.com/embed/mf9TKj0NuTQ'></embed>" } -->

该方案中：

• <Choices>使用choice="single-radio"强制单选用单选框形式呈现（关于single与single-radio的渲染差异见 docs/source/tags/choices.md）；
• <HyperText>负责渲染 HTML 内容（标签参考见 docs/source/tags/hypertext.md）：

<HyperText name="video" value="$html"></HyperText>

输入数据组织

使用 HyperText 方案时，任务数据中的$html字段需要是一段可渲染的 HTML。模板文档给出两种形式。

本地视频文件：

[ { "html": "<video src='examples.com/1.mp4'>" }, { "html": "<video src='examples.com/2.mp4'>" } ]

嵌入网络视频：

[ { "html": "<embed src='https://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 stream=duration -of default=nokey=1:noprint_wrappers=1 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

各参数含义：

该转码流程同样以 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.md）：

  <View> <Video name="video" value="$video" /> <TextArea name="ta" toName="video" /> </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 name="video" value="$video" defaultPlaybackSpeed="2" minPlaybackSpeed="1.5" /> </View>

  这对需要慢速逐帧审视的视频分类（如动作细节判定）尤为实用。

相关标签速查

小结

本文围绕 docs/source/templates/video_classification.md 的官方模板，完整覆盖了两套视频分类配置方案：Video 标签方案适合标准视频文件且支持逐帧标注能力，HyperText 标签方案适合 HTML 嵌入或外部平台视频的粗粒度分类；并给出了参数表、标注结果格式、FFmpeg 转码命令与视频格式要求。落地时建议先按"MP4 + H.264/AAC + 恒定 30fps"完成视频预处理，再基于<Video>+<Choices>的组合创建标注项目，即可快速产出标准化的视频分类训练数据集。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio