云策 WordPress 开发者社区

函数文档

wp_read_video_metadata()

查看官方原文 ↗
💡 云策文档标注

概述

wp_read_video_metadata() 函数用于从视频文件的 ID3 标签中提取元数据。它基于 getID3 库分析文件，返回包含视频关键信息的数组，如比特率、分辨率、时长等，并可通过过滤器进行自定义。

关键要点

  • 函数接受一个必需参数 $file，表示视频文件的路径，返回元数据数组或 false（如果文件不存在）。
  • 内部使用 getID3 库分析视频文件，提取包括 lossless、bitrate、width、height、length、mime_type 等元数据字段。
  • 通过设置 $id3->options_audiovideo_quicktime_ReturnAtomData = true 来获取 created_timestamp 值。
  • 函数包含一个过滤器 wp_read_video_metadata，允许开发者修改返回的元数据数组。
  • 相关函数包括 wp_get_media_creation_timestamp() 和 wp_add_id3_tag_data()，用于辅助处理元数据。

代码示例

// 示例：调用 wp_read_video_metadata() 获取视频元数据
$video_metadata = wp_read_video_metadata('/path/to/video.mp4');
if ($video_metadata !== false) {
    // 处理元数据，例如输出视频宽度
    echo '视频宽度：' . $video_metadata['width'] . 'px';
} else {
    echo '文件不存在或无法读取元数据。';
}

注意事项

  • 确保文件路径正确且文件存在，否则函数返回 false。
  • 元数据提取依赖于 getID3 库，需确保库已正确加载（函数内部会检查并加载）。
  • 过滤器 wp_read_video_metadata 可用于扩展或修改元数据，参数包括 $metadata、$file、$file_format 和 $data。
  • 函数自 WordPress 3.6.0 版本引入，适用于视频附件元数据生成场景。
📄 原文内容

Retrieves metadata from a video file’s ID3 tags.

Parameters

$filestringrequired
Path to file.

Return

array|false Returns array of metadata, if found.

Source

function wp_read_video_metadata( $file ) {
	if ( ! file_exists( $file ) ) {
		return false;
	}

	$metadata = array();

	if ( ! defined( 'GETID3_TEMP_DIR' ) ) {
		define( 'GETID3_TEMP_DIR', get_temp_dir() );
	}

	if ( ! class_exists( 'getID3', false ) ) {
		require ABSPATH . WPINC . '/ID3/getid3.php';
	}

	$id3 = new getID3();
	// Required to get the `created_timestamp` value.
	$id3->options_audiovideo_quicktime_ReturnAtomData = true; // phpcs:ignore WordPress.NamingConventions.ValidVariableName

	$data = $id3->analyze( $file );

	if ( isset( $data['video']['lossless'] ) ) {
		$metadata['lossless'] = $data['video']['lossless'];
	}

	if ( ! empty( $data['video']['bitrate'] ) ) {
		$metadata['bitrate'] = (int) $data['video']['bitrate'];
	}

	if ( ! empty( $data['video']['bitrate_mode'] ) ) {
		$metadata['bitrate_mode'] = $data['video']['bitrate_mode'];
	}

	if ( ! empty( $data['filesize'] ) ) {
		$metadata['filesize'] = (int) $data['filesize'];
	}

	if ( ! empty( $data['mime_type'] ) ) {
		$metadata['mime_type'] = $data['mime_type'];
	}

	if ( ! empty( $data['playtime_seconds'] ) ) {
		$metadata['length'] = (int) round( $data['playtime_seconds'] );
	}

	if ( ! empty( $data['playtime_string'] ) ) {
		$metadata['length_formatted'] = $data['playtime_string'];
	}

	if ( ! empty( $data['video']['resolution_x'] ) ) {
		$metadata['width'] = (int) $data['video']['resolution_x'];
	}

	if ( ! empty( $data['video']['resolution_y'] ) ) {
		$metadata['height'] = (int) $data['video']['resolution_y'];
	}

	if ( ! empty( $data['fileformat'] ) ) {
		$metadata['fileformat'] = $data['fileformat'];
	}

	if ( ! empty( $data['video']['dataformat'] ) ) {
		$metadata['dataformat'] = $data['video']['dataformat'];
	}

	if ( ! empty( $data['video']['encoder'] ) ) {
		$metadata['encoder'] = $data['video']['encoder'];
	}

	if ( ! empty( $data['video']['codec'] ) ) {
		$metadata['codec'] = $data['video']['codec'];
	}

	if ( ! empty( $data['audio'] ) ) {
		unset( $data['audio']['streams'] );
		$metadata['audio'] = $data['audio'];
	}

	if ( empty( $metadata['created_timestamp'] ) ) {
		$created_timestamp = wp_get_media_creation_timestamp( $data );

		if ( false !== $created_timestamp ) {
			$metadata['created_timestamp'] = $created_timestamp;
		}
	}

	wp_add_id3_tag_data( $metadata, $data );

	$file_format = isset( $metadata['fileformat'] ) ? $metadata['fileformat'] : null;

	/**
	 * Filters the array of metadata retrieved from a video.
	 *
	 * In core, usually this selection is what is stored.
	 * More complete data can be parsed from the `$data` parameter.
	 *
	 * @since 4.9.0
	 *
	 * @param array       $metadata    Filtered video metadata.
	 * @param string      $file        Path to video file.
	 * @param string|null $file_format File format of video, as analyzed by getID3.
	 *                                 Null if unknown.
	 * @param array       $data        Raw metadata from getID3.
	 */
	return apply_filters( 'wp_read_video_metadata', $metadata, $file, $file_format, $data );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_read_video_metadata’, array $metadata, string $file, string|null $file_format, array $data )

Filters the array of metadata retrieved from a video.

Uses Description
wp_get_media_creation_timestamp()wp-admin/includes/media.php

Parses creation date from media metadata.
wp_add_id3_tag_data()wp-admin/includes/media.php

Parses ID3v2, ID3v1, and getID3 comments to extract usable data.
get_temp_dir()wp-includes/functions.php

Determines a writable directory for temporary files.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 1 moreShow less

Used by Description
wp_generate_attachment_metadata()wp-admin/includes/image.php

Generates attachment meta data and create image sub-sizes for images.

Changelog

Version Description
3.6.0 Introduced.