media-utils

媒体工具

用于媒体组装的内部工具，由制作者技能使用。

这些脚本封装了 FFmpeg，可提供可靠的媒体处理功能。

前置条件

• 必须安装 FFmpeg：brew install ffmpeg（macOS）或 apt install ffmpeg（Linux）
• 使用以下命令检查：python3 check_ffmpeg.py

可用工具

audio_concat.py

将多个音频文件合并为一个。

# Simple concatenation
python3 audio_concat.py -i intro.wav segment1.wav outro.wav -o podcast.mp3

# With crossfade between clips
python3 audio_concat.py -i track1.wav track2.wav --crossfade 2.0

# With normalization
python3 audio_concat.py -i *.wav -o mixed.mp3 --normalize

audio_mix.py

将语音／旁白与背景音乐混音（可选自动压低背景音乐音量）。

# Voice + music with ducking (music lowers when voice plays)
python3 audio_mix.py --voice narration.wav --music background.mp3 -o final.mp3

# Adjust music volume (default: 0.3)
python3 audio_mix.py --voice voice.wav --music music.mp3 --music-volume 0.2

# No ducking
python3 audio_mix.py --voice voice.wav --music music.mp3 --no-duck

# With fade in/out on music
python3 audio_mix.py --voice voice.wav --music music.mp3 --fade-in 2 --fade-out 3

video_concat.py

合并多个视频片段。

# Simple concatenation
python3 video_concat.py -i clip1.mp4 clip2.mp4 clip3.mp4 -o final.mp4

# With fade transition
python3 video_concat.py -i *.mp4 -o final.mp4 --transition fade --duration 1.0

# Normalize to 1080p
python3 video_concat.py -i *.mp4 -o final.mp4 --resolution 1080p

# Available transitions: fade, dissolve, wipeleft, wiperight, slideup, slidedown

video_audio_merge.py

为视频添加音轨。

# Replace video audio
python3 video_audio_merge.py --video clip.mp4 --audio voiceover.mp3 -o final.mp4

# Add voice + music with ducking
python3 video_audio_merge.py --video clip.mp4 --voice narration.wav --music bg.mp3

# Mix with existing video audio
python3 video_audio_merge.py --video clip.mp4 --audio music.mp3 --mix

# Audio sync offset
python3 video_audio_merge.py --video clip.mp4 --audio audio.mp3 --offset 0.5

video_strip_audio.py

移除视频文件中的音频（以便替换为自定义音频）。

# Strip audio from single file
python3 video_strip_audio.py -i video.mp4 -o silent_video.mp4

# Strip audio from multiple files (batch mode)
python3 video_strip_audio.py -i clip1.mp4 clip2.mp4 clip3.mp4

# Strip with custom output directory
python3 video_strip_audio.py -i *.mp4 --output-dir ./silent/

# Re-encode video instead of copying
python3 video_strip_audio.py -i video.mp4 --reencode

check_ffmpeg.py

验证 FFmpeg 是否已安装。

python3 check_ffmpeg.py
# ✅ FFmpeg is available!
#    ffmpeg version 6.0 ...

report_to_pdf.py

将 Markdown 报告转换为专业的 PDF 文档。

# Basic conversion
python3 report_to_pdf.py -i analysis.md -o analysis.pdf

# With custom title and executive style
python3 report_to_pdf.py -i report.md -o report.pdf --title "Q4 Market Analysis" --style executive

# Technical documentation with table of contents
python3 report_to_pdf.py -i docs.md -o docs.pdf --style technical --toc

可用样式：

样式	描述
business	简洁、专业（默认）
executive	使用较大字体的执行摘要
technical	技术文档
minimal	最简样式，内容尽可能丰富

依赖： pip install markdown weasyprint

制作者技能的用法

制作者技能会调用这些工具来组装最终输出：

from pathlib import Path
import subprocess
import sys

# Get path to media-utils
UTILS_PATH = Path(__file__).parent.parent.parent / "media-utils" / "scripts"

def concat_audio(files: list, output: str):
    cmd = [
        sys.executable,
        str(UTILS_PATH / "audio_concat.py"),
        "-i", *files,
        "-o", output
    ]
    subprocess.run(cmd, check=True)

输出格式

工具	默认输出	选项
audio_concat	MP3	继承自输入
audio_mix	MP3	MP3
video_concat	MP4 (H.264)	MP4
video_audio_merge	MP4 (H.264)	MP4
video_strip_audio	MP4 (copy)	MP4