如何在 Java 中使用 GroupDocs.Metadata 提取 mkv 元数据

在本综合指南中，您将学习 如何在 Java 中使用 GroupDocs.Metadata 库提取 mkv 元数据。无论是构建媒体目录、验证编码参数，还是自动生成缩略图，使用编程方式读取 Matroska（MKV）元数据都能节省大量手动工作时间。我们将逐步介绍原因、前置条件、具体的设置步骤以及详细的代码片段，展示如何获取 EBML 头、段信息、标签和轨道数据。

快速答案

  • “read mkv metadata java” 是什么意思？ 指使用 Java 对 Matroska 容器的元数据（标题、编解码器、时长等）进行程序化提取。
  • 应该使用哪个库？ GroupDocs.Metadata for Java 提供了功能完整、高性能的 Matroska 以及 50 多种其他格式的 API。
  • 需要许可证吗？ 免费试用可用于评估；商业许可证可移除所有试用限制。
  • 可以读取其他格式吗？ 可以——同一 API 可读取 MP4、AVI、MOV、MP3 等众多容器。
  • 运行时需要网络访问吗？ 不需要——所有提取工作在本地完成，只要 JAR 在类路径中即可。

什么是 Matroska (MKV) 元数据？

Matroska (MKV) 元数据是存储在 Matroska 容器内部的结构化和描述性信息集合，包括 EBML 头（文件版本和文档类型）、段详情（时长、复用应用）、用户自定义标签（标题、描述）以及轨道规格（音视频编解码器 ID、语言、比特率）。访问这些数据可帮助您构建可搜索的目录、验证文件完整性，或驱动自动化工作流（如生成缩略图）。

为什么在 Java 中读取 mkv 元数据？

在 Java 中读取 MKV 元数据可以 自动化 数千个视频文件的目录编制，验证 编解码器和语言要求后再发布，并 填充 包含标题、时长和轨道语言的可搜索数据库。它还提供了一个 统一的代码库 来从多种容器中提取视频元数据，降低维护成本，并确保在媒体流水线中进行一致的质量检查。

为什么选择 GroupDocs.Metadata for Java？

GroupDocs.Metadata for Java 是一款成熟的库，支持 50+ 输入和输出格式，包括 Matroska、MP4、AVI 和 MOV。它以流式方式读取容器结构，即使是多 GB 的文件也能保持低内存消耗。API 抽象了底层 EBML 解析，让您专注于业务逻辑。只需添加一个 Maven 依赖即可完成集成，且库会持续更新以兼容最新的编解码器规范。

前置条件

  • GroupDocs.Metadata for Java 版本 24.12 或更高。
  • 已安装 Java Development Kit (JDK) 8 或更高。
  • 使用 Maven（或手动管理 JAR）来处理依赖。
  • 用于测试的 MKV 文件，放置在代码可引用的文件夹中（例如 YOUR_DOCUMENT_DIRECTORY）。

为 Java 设置 GroupDocs.Metadata

GroupDocs.Metadata for Java 是一个能够读取超过 50 种文件格式元数据的库，包括 Matroska (MKV)。使用 Maven 添加或手动下载 JAR 即可。

Maven:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/metadata/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-metadata</artifactId>
      <version>24.12</version>
   </dependency>
</dependencies>

直接下载:
如果不想使用 Maven，可从 GroupDocs.Metadata for Java releases 下载最新版本。

获取许可证

先使用免费试用探索功能。生产环境请购买许可证，或从 GroupDocs 获取临时许可证，以移除试用限制。

基本初始化和设置

下面的代码展示了使用 GroupDocs.Metadata 打开 MKV 文件的最小示例。

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.MatroskaRootPackage;

public class MetadataExtraction {
    public static void main(String[] args) {
        try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY/input.mkv")) {
            MatroskaRootPackage root = metadata.getRootPackageGeneric();
            // Access and manipulate metadata here
        }
    }
}

如何使用 GroupDocs.Metadata 在 Java 中读取 mkv 元数据

Metadata 是表示 MKV 文件并提供其元数据访问的主类。
使用 new Metadata("path/to/file.mkv") 加载 MKV 文件，然后调用相应的 getter——getRootPackageGeneric()、getSegments()、getTags() 和 getTracks()——即可获取每个元数据段。此单一调用链让您无需编写底层解析逻辑，即可完整查看 EBML 头、段信息、用户标签以及各轨道细节。

读取 Matroska EBML 头

EBML 头存储核心文件信息，如版本、文档类型和文件大小。
getRootPackageGeneric() 返回已打开文件的 EBML 头包。

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.MatroskaRootPackage;

public class ReadMatroskaEBMLHeader {
    public static void run() {
        try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY/input.mkv")) {
            MatroskaRootPackage root = metadata.getRootPackageGeneric();

            String docType = root.getMatroskaPackage().getEbmlHeader().getDocType();
            String docTypeReadVersion = root.getMatroskaPackage().getEbmlHeader().getDocTypeReadVersion();
            String docTypeVersion = root.getMatroskaPackage().getEbmlHeader().getDocTypeVersion();
            String readVersion = root.getMatroskaPackage().getEbmlHeader().getReadVersion();
            String version = root.getMatroskaPackage().getEbmlHeader().getVersion();

            // Use the extracted header details as needed
        }
    }
}

关键点

  • getRootPackageGeneric() 返回 Matroska 包的入口点。
  • EBML 属性（docType、version 等）可在深入处理前帮助您验证文件兼容性。

读取 Matroska 段信息

段描述整体媒体时间线、创建工具以及可选的标题信息。
getSegments() 检索包含时长和创建细节的段对象集合。

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.MatroskaRootPackage;

public class ReadMatroskaSegmentInformation {
    public static void run() {
        try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY/input.mkv")) {
            MatroskaRootPackage root = metadata.getRootPackageGeneric();

            for (var segment : root.getMatroskaPackage().getSegments()) {
                String dateUtc = segment.getDateUtc();
                long duration = segment.getDuration();
                String muxingApp = segment.getMuxingApp();
                String segmentFilename = segment.getSegmentFilename();
                String segmentUid = segment.getSegmentUid();
                long timecodeScale = segment.getTimecodeScale();
                String title = segment.getTitle();
                String writingApp = segment.getWritingApp();

                // Process the extracted segment information as needed
            }
        }
    }
}

关键点

  • getSegments() 返回一个集合；每个段可拥有自己的标题、时长和创建应用信息。
  • 这些数据对于构建播放列表或在批量文件中验证编码参数非常有用。

读取 Matroska 标签元数据

标签存储人类可读的信息，如标题、艺术家或自定义备注。
getTags() 返回与文件关联的标签条目列表。

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.MatroskaRootPackage;
import com.groupdocs.metadata.core.MetadataProperty;

public class ReadMatroskaTagMetadata {
    public static void run() {
        try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY/input.mkv")) {
            MatroskaRootPackage root = metadata.getRootPackageGeneric();

            for (var tag : root.getMatroskaPackage().getTags()) {
                String targetType = tag.getTargetType();
                String targetTypeValue = tag.getTargetTypeValue();
                String tagTrackUid = tag.getTagTrackUid();

                for (MetadataProperty simpleTag : tag.getSimpleTags()) {
                    String name = simpleTag.getName();
                    String value = simpleTag.getValue();

                    // Utilize the extracted tag information as needed
                }
            }
        }
    }
}

关键点

  • 标签按 targetType（例如 movie、track）组织。
  • simpleTag 条目保存键/值对，如 TITLE=My Video。

读取 Matroska 轨道元数据

轨道代表容器内的音频、视频或字幕流。
getTracks() 提供对每条轨道技术规格的访问。

import com.groupdocs.metadata.Metadata;
import com.groupdocs.metadata.core.MatroskaRootPackage;

public class ReadMatroskaTrackMetadata {
    public static void run() {
        try (Metadata metadata = new Metadata("YOUR_DOCUMENT_DIRECTORY/input.mkv")) {
            MatroskaRootPackage root = metadata.getRootPackageGeneric();

            for (var track : root.getMatroskaPackage().getTracks()) {
                String trackType = track.getType();
                String codecId = track.getCodecId();
                String language = track.getLanguage();
                long duration = track.getDuration();
                
                // Process the extracted track information as needed
            }
        }
    }
}

关键点

  • track.getType() 告诉您流是视频、音频还是字幕。
  • codecId 标识编解码器（例如 V_MPEG4/ISO/AVC）。
  • 这些信息对转码流水线、质量检查和动态流媒体决策至关重要。

读取 mkv 元数据 java 的常见用例

  • 媒体目录 – 将标题、时长和语言代码填充到数据库表中，以实现快速搜索。
  • 自动化质量控制 – 在发布前验证每个文件是否包含必需标签并符合编解码器标准。
  • 动态流媒体 – 在运行时根据用户偏好选择合适的音频或字幕轨道。
  • 内容迁移 – 一次提取元数据后，将其注入新存储系统或内容分发网络。

常见问题与故障排除

症状可能原因解决方案
访问 getEbmlHeader() 时出现 NullPointerException文件路径不正确或文件未找到检查 new Metadata("...") 中的路径，并确保磁盘上存在该文件。
未返回标签MKV 文件缺少标签元素使用包含元数据标签的媒体文件（例如通过 MKVToolNix 添加的）。
大文件处理缓慢堆内存不足增加 JVM 堆内存 (-Xmx2g 或更高)，或在可能的情况下分块处理文件。

常见问答

问：我可以使用同一库提取其他视频格式的元数据吗？
答：可以，GroupDocs.Metadata 支持 MP4、AVI、MOV 等众多格式。API 使用方式相同——只需针对相应格式使用对应的根包类。

问：生产环境是否需要许可证？
答：商业许可证可移除试用限制并解锁全部功能。库在试用模式下可用于评估。

问：提取过程是否离线进行？
答：完全离线。只要 JAR 在类路径中，所有元数据读取均在本地完成，无需网络调用。

问：库在处理非常大的 MKV 文件（数 GB）时表现如何？
答：库采用流式读取容器结构，保持内存使用量适中。确保 JVM 有足够的堆空间来容纳可能的大型标签集合，必要时提升 -Xmx 参数。

问：我可以修改元数据并写回文件吗？
答：GroupDocs.Metadata 主要侧重于读取。写入支持有限，请参考最新 API 文档了解写回功能。

最后更新： 2026-09-02
测试环境： GroupDocs.Metadata 24.12 for Java
作者： GroupDocs

相关教程