parseMedia() 與 getVideoMetadata() 的差異
比較 Remotion 中 parseMedia() 和 getVideoMetadata() 兩個 API 的差異，說明各自的使用情境、功能範圍與遷移建議。
parseMedia() 與 getVideoMetadata() 的差異
這兩個函式都是做什麼的？
兩者都用於讀取媒體檔案（影片、音訊）的中繼資料（metadata），例如時長、解析度、幀率等。但它們在設計理念、功能範圍和實作方式上有顯著差異。
getVideoMetadata() 是什麼？
getVideoMetadata() 來自 @remotion/media-utils 套件，是較早期的 API：
import { getVideoMetadata } from "@remotion/media-utils";
const metadata = await getVideoMetadata(videoSrc);
console.log(metadata.durationInSeconds);
console.log(metadata.width);
console.log(metadata.height);
console.log(metadata.fps);它透過在瀏覽器中載入媒體檔案並讀取 HTML 媒體元素的屬性來獲取資訊。
parseMedia() 是什麼？
parseMedia() 來自 @remotion/media-parser 套件，是較新的 API：
import { parseMedia } from "@remotion/media-parser";
const result = await parseMedia({
src: videoSrc,
fields: {
durationInSeconds: true,
dimensions: true,
fps: true,
videoCodec: true,
audioCodec: true,
tracks: true,
},
});它直接解析媒體檔案的二進制格式（如 MP4、WebM 容器），獲取更豐富且更精確的中繼資料。
兩者的主要差異
| 特性 | getVideoMetadata() | parseMedia() |
|---|---|---|
| 套件 | @remotion/media-utils | @remotion/media-parser |
| 實作方式 | 瀏覽器 HTMLMediaElement | 直接解析二進制格式 |
| 可用環境 | 僅瀏覽器 | 瀏覽器 + Node.js |
| 資訊豐富度 | 基本資訊 | 詳細的容器和編解碼器資訊 |
| 精確度 | 依賴瀏覽器解析 | 直接讀取容器標頭，更精確 |
| 速度 | 需要完全載入或等待 | 通常只需讀取檔案頭部 |
| 支援格式 | 瀏覽器支援的格式 | MP4、WebM、AVI 等主流格式 |
| 串流支援 | 不支援 | 支援邊下載邊解析 |
什麼情況下應該使用 getVideoMetadata()？
- 你的專案已經在使用它，且功能符合需求
- 你只需要基本的時長和尺寸資訊
- 你只在瀏覽器環境中使用
什麼情況下應該使用 parseMedia()？
- 需要在 Node.js 伺服器端讀取媒體資訊
- 需要詳細的編解碼器資訊（例如判斷影片是 H.264 還是 H.265）
- 需要讀取所有音訊和影片軌道的詳細資訊
- 需要更快速、更精確的元數據讀取
- 正在開發新專案
parseMedia() 可以取得哪些額外資訊？
parseMedia() 提供的資訊遠比 getVideoMetadata() 豐富：
const result = await parseMedia({
src: "video.mp4",
fields: {
videoCodec: true, // "h264", "h265", "vp8", "vp9"...
audioCodec: true, // "aac", "mp3", "opus"...
tracks: true, // 詳細的軌道資訊
container: true, // "mp4", "webm"...
slowFps: true, // 精確幀率
rotation: true, // 影片旋轉角度
unrotatedDimensions: true, // 未旋轉前的原始尺寸
isHdr: true, // 是否為 HDR 內容
},
});官方建議使用哪一個？
官方建議在新專案中使用 parseMedia()。 它是功能更強大、更現代化的 API，並且在瀏覽器和 Node.js 環境中都能使用。
getVideoMetadata() 仍然被維護，但新功能會優先加入 parseMedia()。
如何從 getVideoMetadata() 遷移到 parseMedia()？
// 舊方式
import { getVideoMetadata } from "@remotion/media-utils";
const { durationInSeconds, width, height } = await getVideoMetadata(src);
// 新方式
import { parseMedia } from "@remotion/media-parser";
const {
durationInSeconds,
dimensions: { width, height },
} = await parseMedia({
src,
fields: {
durationInSeconds: true,
dimensions: true,
},
});