octave_ffmpeg_free文档

欢迎广大开发者将此文档翻译为其他语言。

软件源安装

octave_ffmpeg_free可以通过Octave软件源安装。

通过Octave软件源安装octave_ffmpeg_free，代码如下：

>> pkg install -forge octave_ffmpeg_free

在线安装

octave_ffmpeg_free可以在线安装。

在线安装octave_ffmpeg_free，代码如下：

>> pkg install 'https://github.com/CNOCTAVE/octave_ffmpeg_free/releases/download/1.1.0/octave_ffmpeg_free.tar.gz'

源码安装

octave_ffmpeg_free可以直接使用tar包安装。

假设你下载的源码包名为octave_ffmpeg_free.tar.gz，源码安装的代码如下：

>> pkg install octave_ffmpeg_free.tar.gz -local

如何使用

在安装后，加载octave_ffmpeg_free即可使用，代码如下：

>> pkg load octave_ffmpeg_free

依赖库

不同的Linux发行版有不同的依赖库名。

Fedora：

$ sudo dnf install libavutil-free libavutil-free-devel libavformat-free libavformat-free-devel libavcodec-free libavcodec-free-devel libswresample-free libswresample-free-devel libavfilter-free libavfilter-free-devel

在其他的Linux发行版上的命令有所不同。欢迎广大开发者补充。

函数用法

octave_ffmpeg_free 提供以下 C/C++ 底层可加载函数和 Octave 封装函数，涵盖音频处理、视频处理、元数据管理、媒体分析等能力。

一、媒体信息与调试

av_dump_format

Loadable Function: 0 = av_dump_format(input_filename)

调用 FFmpeg 的 av_dump_format() 函数，打印媒体文件的格式、流信息、编码参数等详细信息到控制台。始终返回 0。

二、音频处理

ffmpeg_audio_open

Loadable Function: [info, audio_data, sample_rate] = ffmpeg_audio_open(filename)

打开音频文件并返回音频流信息。info 为结构体（包含采样率、声道数、采样格式、时长等），audio_data 为音频数据矩阵（NxM，N 为样本数，M 为声道数），sample_rate 为采样率。如果只有一个输出参数，则只返回 info 信息，不读取音频数据。

ffmpeg_audio_encode

Loadable Function: ffmpeg_audio_encode(audio_data, sample_rate, output_filename)

Loadable Function: ffmpeg_audio_encode(audio_data, sample_rate, output_filename, codec_name)

将音频数据编码写入文件。audio_data 为 NxM 矩阵，sample_rate 为采样率（Hz），output_filename 为输出文件路径。codec_name 为可选编码器名称（默认 libmp3lame）。

ffmpeg_audio_features

Loadable Function: features = ffmpeg_audio_features(audio_data, sample_rate)

提取音频声学特征，返回结构体包含：.zero_crossing_rate（过零率）、.spectral_centroid（谱质心，Hz）、.spectral_rolloff（谱滚降，Hz，85%能量）、.rms_energy（RMS能量）、.mfcc（MFCC系数，13维）。

ffmpeg_audio_filter

Loadable Function: filtered_audio = ffmpeg_audio_filter(audio_data, sample_rate, filter_description)

应用 FFmpeg 音频滤镜到音频数据。filter_description 示例："ahighpass=frequency=300"（高通滤波）、"alowpass=frequency=3000"（低通滤波）、"aecho=0.8:0.9:1000:0.3"（回声效果）、"equalizer=f=1000:t=q:w=1:g=5"（均衡器）、"volume=0.5"（音量调整）、"atempo=1.5"（变速不变调）。

ffmpeg_audio_spectrum

Loadable Function: [magnitude, frequency] = ffmpeg_audio_spectrum(audio_data, sample_rate)

Loadable Function: [magnitude, frequency] = ffmpeg_audio_spectrum(audio_data, sample_rate, fft_size)

计算音频频谱。audio_data 为 NxM 矩阵，sample_rate 为采样率，fft_size 可选（默认 1024）。返回 magnitude（幅度谱，FFT点数/2+1 行 x M 列）和 frequency（频率轴）。

ffmpeg_audio_waveform

Loadable Function: [waveform, time] = ffmpeg_audio_waveform(audio_data, sample_rate)

Loadable Function: [waveform, time] = ffmpeg_audio_waveform(audio_data, sample_rate, window_size)

提取音频波形包络（RMS值）。window_size 可选（默认 1024），返回 waveform（每个窗口的RMS值）和 time（时间轴，秒）。

ffmpeg_lrc_parse

Loadable Function: lyrics = ffmpeg_lrc_parse(lrc_filename)

解析 LRC 歌词文件。返回结构体数组，每个元素包含 .time（秒）和 .text（歌词文本），以及 .meta 结构体包含元数据（ti、ar、al、by 等）。支持 [mm:ss.xx] 和 [mm:ss:xx] 格式。

三、视频处理

ffmpeg_video_open

Loadable Function: [info, frames] = ffmpeg_video_open(filename)

Loadable Function: [info, frames, fps] = ffmpeg_video_open(filename, max_frames)

打开视频文件并返回视频流信息和帧数据。info 为结构体（宽度、高度、编码、时长、帧率等），frames 为 HxWxCxN 四维 uint8 数组（C=3 RGB），fps 为帧率。

ffmpeg_video_to_images

Loadable Function: [frames, info] = ffmpeg_video_to_images(filename)

Loadable Function: ffmpeg_video_to_images(filename, output_pattern)

Loadable Function: ffmpeg_video_to_images(filename, output_pattern, max_frames)

从视频中提取帧并保存为图像文件或返回帧数据。output_pattern 示例：'frame_%04d.png'。帧数据格式为 HxWx3xN uint8 数组。

ffmpeg_video_filter

Loadable Function: filtered_frames = ffmpeg_video_filter(frames, filter_description)

应用 FFmpeg 视频滤镜到帧数据。filter_description 示例："hflip"（水平翻转）、"vflip"（垂直翻转）、"rotate=45*PI/180"（旋转45度）、"scale=iw/2:ih/2"（缩放一半）、"hue=h=60:s=1"（色调调整）、"drawtext=text='Hello':fontsize=24:x=10:y=10"（添加文字）、"fps=10"（改变帧率）。

ffmpeg_video_motion

Loadable Function: motion = ffmpeg_video_motion(frames)

Loadable Function: motion = ffmpeg_video_motion(frames, threshold)

视频运动检测（帧差法）。frames 为 HxWx3xN uint8 视频帧，threshold 可选（默认 30）。返回 motion（每帧的运动量，N-1 行向量）和可选 diff_frames（帧差图像）。

ffmpeg_video_quality

Loadable Function: [psnr, ssim] = ffmpeg_video_quality(original_frames, processed_frames)

计算视频质量指标 PSNR 和 SSIM。original_frames 和 processed_frames 均为 HxWx3xN 视频帧。返回 psnr（PSNR 值，dB，每帧）和 ssim（SSIM 值，0-1，每帧）。

ffmpeg_video_scene

Loadable Function: [scene_changes, scores] = ffmpeg_video_scene(frames)

Loadable Function: [scene_changes, scores] = ffmpeg_video_scene(frames, threshold)

视频场景切换检测（直方图比较法）。frames 为 HxWx3xN uint8 视频帧，threshold 可选（默认 0.3）。返回 scene_changes（场景切换的帧索引，0-based）和 scores（连续帧之间的差异分数）。

四、元数据管理

ffmpeg_get_metadata

Loadable Function: metadata = ffmpeg_get_metadata(input_filename)

获取媒体文件的所有元数据。返回结构体，每个字段对应一个元数据标签（如 title、artist、album、date、genre 等）。

ffmpeg_set_metadata

Loadable Function: metadata = ffmpeg_set_metadata(input_filename, output_filename, metadata_dict)

设置媒体文件的元数据。输入源文件名、输出文件名和元数据字典（ID3 结构体），在不重新编码的情况下复制流数据并写入新的元数据。

ffmpeg_save_audio_cover

Loadable Function: metadata = ffmpeg_save_audio_cover(input_filename, output_filename)

从音频文件中提取并保存封面图片。输入音频文件名和输出图片文件名。

ffmpeg_side_data

Loadable Function: side_data = ffmpeg_side_data(input_filename)

Loadable Function: side_data = ffmpeg_side_data(input_filename, stream_type)

读取媒体文件中数据包的边数据（Side Data）。stream_type 可选（'video' 或 'audio'，默认 'video'）。返回结构体数组，包含 .type（边数据类型）、.data（边数据数值数组）、.size（数据大小）。

五、元数据读取封装函数

ffmpeg_get_default_id3_metadata

Function File: id3_struct = ffmpeg_get_default_id3_metadata()

获取默认 ID3 元数据结构体，包含 album_artist、album、artist、comment、composer、date、disc、genre、language、mood、set、subtitle、title、track 等默认字段。

ffmpeg_get_attr

Function File: ret = ffmpeg_get_attr(input_filename, attribute_name)

获取媒体文件的任意属性值。输入文件名和属性名，返回对应的属性值字符串。如果属性不存在则返回空字符串。

ffmpeg_get_title / ffmpeg_get_artist / ffmpeg_get_album

Function File: ret = ffmpeg_get_title(input_filename)

Function File: ret = ffmpeg_get_artist(input_filename)

Function File: ret = ffmpeg_get_album(input_filename)

分别获取媒体文件的标题、艺术家、专辑名。如果标签不存在则返回空字符串。

ffmpeg_get_album_artist / ffmpeg_get_composer / ffmpeg_get_performer

Function File: ret = ffmpeg_get_album_artist(input_filename)

Function File: ret = ffmpeg_get_composer(input_filename)

Function File: ret = ffmpeg_get_performer(input_filename)

分别获取媒体文件的专辑艺术家、作曲者、表演者。如果标签不存在则返回空字符串。

ffmpeg_get_genre / ffmpeg_get_comment / ffmpeg_get_language

Function File: ret = ffmpeg_get_genre(input_filename)

Function File: ret = ffmpeg_get_comment(input_filename)

Function File: ret = ffmpeg_get_language(input_filename)

分别获取媒体文件的流派、评论、语言。如果标签不存在则返回空字符串。

ffmpeg_get_date / ffmpeg_get_TYER / ffmpeg_get_disc / ffmpeg_get_track

Function File: ret = ffmpeg_get_date(input_filename)

Function File: ret = ffmpeg_get_TYER(input_filename)

Function File: ret = ffmpeg_get_disc(input_filename)

Function File: ret = ffmpeg_get_track(input_filename)

分别获取媒体文件的日期、TYER（年份）、碟号、音轨号。如果标签不存在则返回空字符串。

ffmpeg_get_publisher / ffmpeg_get_copyright / ffmpeg_get_encoded_by / ffmpeg_get_encoder

Function File: ret = ffmpeg_get_publisher(input_filename)

Function File: ret = ffmpeg_get_copyright(input_filename)

Function File: ret = ffmpeg_get_encoded_by(input_filename)

Function File: ret = ffmpeg_get_encoder(input_filename)

分别获取媒体文件的发布者、版权、编码者、编码器信息。如果标签不存在则返回空字符串。

ffmpeg_get_creation_time / ffmpeg_get_tagging_time

Function File: ret = ffmpeg_get_creation_time(input_filename)

Function File: ret = ffmpeg_get_tagging_time(input_filename)

分别获取媒体文件的创建时间和标记时间。如果标签不存在则返回空字符串。

ffmpeg_get_filename / ffmpeg_get_video_size / ffmpeg_get_variant_bitrate / ffmpeg_get_pixel_format

Function File: ret = ffmpeg_get_filename(input_filename)

Function File: ret = ffmpeg_get_video_size(input_filename)

Function File: ret = ffmpeg_get_variant_bitrate(input_filename)

Function File: ret = ffmpeg_get_pixel_format(input_filename)

分别获取媒体文件的文件名、视频尺寸、可变比特率、像素格式。如果标签不存在则返回空字符串。

ffmpeg_get_service_name / ffmpeg_get_service_provider

Function File: ret = ffmpeg_get_service_name(input_filename)

Function File: ret = ffmpeg_get_service_provider(input_filename)

分别获取媒体文件的服务名称和服务提供商。如果标签不存在则返回空字符串。

六、元数据设置封装函数

ffmpeg_set_id3_struct_attr

Function File: id3_struct = ffmpeg_set_id3_struct_attr(id3_struct, attr, value)

设置 ID3 结构体的任意属性。输入 ID3 结构体、属性名和属性值（均为字符串），返回修改后的结构体。

ffmpeg_set_id3_struct_album

Function File: id3_struct = ffmpeg_set_id3_struct_album(id3_struct, value)

设置 ID3 结构体的专辑（album）字段。value 应为字符串。

ffmpeg_set_id3_struct_album_artist

Function File: id3_struct = ffmpeg_set_id3_struct_album_artist(id3_struct, value)

设置 ID3 结构体的专辑艺术家（album_artist）字段。

ffmpeg_set_id3_struct_artist / ffmpeg_set_id3_struct_title

Function File: id3_struct = ffmpeg_set_id3_struct_artist(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_title(id3_struct, value)

分别设置 ID3 结构体的艺术家（artist）和标题（title）字段。

ffmpeg_set_id3_struct_comment / ffmpeg_set_id3_struct_composer

Function File: id3_struct = ffmpeg_set_id3_struct_comment(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_composer(id3_struct, value)

分别设置 ID3 结构体的评论（comment）和作曲者（composer）字段。

ffmpeg_set_id3_struct_copyright / ffmpeg_set_id3_struct_creation_time

Function File: id3_struct = ffmpeg_set_id3_struct_copyright(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_creation_time(id3_struct, value)

分别设置 ID3 结构体的版权（copyright）和创建时间（creation_time）字段。

ffmpeg_set_id3_struct_date / ffmpeg_set_id3_struct_disc

Function File: id3_struct = ffmpeg_set_id3_struct_date(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_disc(id3_struct, value)

分别设置 ID3 结构体的日期（date）和碟号（disc）字段。

ffmpeg_set_id3_struct_encoded_by / ffmpeg_set_id3_struct_encoder

Function File: id3_struct = ffmpeg_set_id3_struct_encoded_by(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_encoder(id3_struct, value)

分别设置 ID3 结构体的编码者（encoded_by）和编码器（encoder）字段。

ffmpeg_set_id3_struct_genre / ffmpeg_set_id3_struct_language

Function File: id3_struct = ffmpeg_set_id3_struct_genre(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_language(id3_struct, value)

分别设置 ID3 结构体的流派（genre）和语言（language）字段。

ffmpeg_set_id3_struct_performer / ffmpeg_set_id3_struct_publisher

Function File: id3_struct = ffmpeg_set_id3_struct_performer(id3_struct, value)

Function File: id3_struct = ffmpeg_set_id3_struct_publisher(id3_struct, value)

分别设置 ID3 结构体的表演者（performer）和发布者（publisher）字段。

ffmpeg_set_id3_struct_track

Function File: id3_struct = ffmpeg_set_id3_struct_track(id3_struct, value)

设置 ID3 结构体的音轨号（track）字段。

常见用例

获取媒体文件元数据：

>> metadata = ffmpeg_get_metadata("audio.mp3")

>> title = ffmpeg_get_title("audio.mp3")

>> artist = ffmpeg_get_artist("audio.mp3")

>> album = ffmpeg_get_album("audio.mp3")

设置媒体文件元数据：

>> id3 = ffmpeg_get_default_id3_metadata();

>> id3 = ffmpeg_set_id3_struct_title(id3, "My Song");

>> id3 = ffmpeg_set_id3_struct_artist(id3, "My Artist");

>> ffmpeg_set_metadata("input.mp3", "output.mp3", id3);

打开并分析音频文件：

>> [info, data, fs] = ffmpeg_audio_open("audio.mp3");

>> [magnitude, freq] = ffmpeg_audio_spectrum(data, fs);

>> features = ffmpeg_audio_features(data, fs);

应用音频滤镜：

>> filtered = ffmpeg_audio_filter(data, fs, "volume=0.5");

>> filtered = ffmpeg_audio_filter(data, fs, "ahighpass=frequency=200");

打开并分析视频文件：

>> [info, frames] = ffmpeg_video_open("video.mp4");

>> motion = ffmpeg_video_motion(frames);

>> [changes, scores] = ffmpeg_video_scene(frames);

视频滤镜和帧提取：

>> flipped = ffmpeg_video_filter(frames, "hflip");

>> [frames, info] = ffmpeg_video_to_images("video.mp4");

解析 LRC 歌词文件：

>> lyrics = ffmpeg_lrc_parse("song.lrc");

引用octave_ffmpeg_free

如果你在学术研究中涉及octave_ffmpeg_free，那么可以按需引用以下内容。

octave_ffmpeg_free源码(BibTeX)

@misc{CNOCTAVE2024, author = {Yu Hongbo, }, title = {octave_ffmpeg_free}, year = {2024}, howpublished = {\url{https://github.com/CNOCTAVE/octave_ffmpeg_free}}, }

octave_ffmpeg_free文档(BibTeX)

@techreport{CNOCTAVE2024, author = {Yu Hongbo, }, title = {octave_ffmpeg_free Document}, institution = {BA DU XIN SHANG}, year = {2024}, number = {1}, month = {10}, url = {https://cnoctave.github.io/octave_ffmpeg_free/index.html}, urldate = {2024-10-07}, }

octave_ffmpeg_free: A Comprehensive Multimedia Processing Package for GNU Octave(BibTeX)

@article{https://engrxiv.org/preprint/view/4192, doi = {10.31224/4192}, url = {https://engrxiv.org/preprint/view/4192}, author = {Yu Hongbo, }, keywords = {CNOCTAVE, GNU, FFmpeg, multimedia processing, audio analysis, video processing, signal processing, open-source software, creative tools}, title = {octave_ffmpeg_free: A Comprehensive Multimedia Processing Package for GNU Octave}, publisher = {engrxiv}, year = {2024}, copyright = {Creative Commons Attribution 4.0 International}, }