用户指南#

本综合指南涵盖了使用 dftt_timecode 的各个方面。

概述#

dftt_timecode 是一个为影视行业设计的综合性 Python 库，用于高精度处理各种格式的时码。它支持高达 999.99 fps 的高帧率（HFR），并提供丰富的时码操作功能。

核心概念#

时码类型#

该库支持在不同场景下使用的多种时码格式：

  • SMPTE：行业标准格式（HH:MM:SS:FF）

  • SRT：SubRip 字幕格式（HH:MM:SS,mmm）

  • FFMPEG：FFmpeg 时间戳格式（HH:MM:SS.ff）

  • FCPX：Final Cut Pro X 格式（frames/fps）

  • DLP：数字电影格式（HH:MM:SS:FFF）

  • Frame：简单的帧计数

  • Time：基于秒的时间戳

帧率#

该库支持：

  • 标准帧率（23.976、24、25、29.97、30、50、59.94、60 等）

  • 高帧率（96、100、120、144、240 等）

  • 0.01 到 999.99 fps 的自定义帧率

  • 使用 Python 的 Fraction 类型的精确分数帧率

跳帧 vs 非跳帧#

对于 NTSC 视频标准（29.97 fps、59.94 fps），该库正确处理：

  • 非跳帧（NDF）：使用冒号分隔符（HH:MM:SS:FF）

  • 跳帧（DF）：使用分号分隔符（HH:MM:SS;FF）

跳帧时码通过定期跳过帧编号来补偿名义帧率和实际帧率之间的微小差异。

严格模式#

严格模式确保时码保持在 24 小时周期内：

  • 启用：时码在 24 小时处循环（25:00:00:00 变为 01:00:00:00）

  • 禁用：时码可以超过 24 小时（适用于长篇内容）

常见使用场景#

视频编辑#

from dftt_timecode import DfttTimecode

# Define edit points
in_point = DfttTimecode('01:05:23:12', 'auto', fps=23.976)
out_point = DfttTimecode('01:08:45:18', 'auto', fps=23.976)

# Calculate duration
duration = out_point - in_point
print(f"Clip duration: {duration.timecode_output('smpte')}")

字幕时间轴#

# SRT format for subtitles
start = DfttTimecode('00:01:23,456', 'auto', fps=25)
end = DfttTimecode('00:01:27,890', 'auto', fps=25)

# Convert to SMPTE for editing
print(f"Start: {start.timecode_output('smpte')}")
print(f"End: {end.timecode_output('smpte')}")

帧率转换#

# Convert from 24fps to 30fps
tc_24 = DfttTimecode('01:00:00:00', 'auto', fps=24)
tc_24.set_fps(30, rounding=True)
print(tc_24.timecode_output('smpte'))

高帧率工作流#

# Working with high frame rate content
hfr_tc = DfttTimecode('00:10:00:000', 'auto', fps=120)

# Convert to standard frame rate for delivery
hfr_tc.set_fps(24, rounding=True)
print(hfr_tc.timecode_output('smpte'))

最佳实践#

  1. 标准工作流使用严格模式：为典型的视频编辑启用严格模式，以防止时码值超过 24 小时。

  2. 明确指定帧率：创建时码对象时始终指定正确的帧率，以确保准确转换。

  3. 使用 Fraction 获得精确帧率：对于 23.976 或 29.97 等帧率，使用 Fraction 以获得最大精度：

    from fractions import Fraction
fps = Fraction(24000, 1001)  # Exactly 23.976023976...

  4. 正确处理跳帧：使用 NTSC 帧率（29.97、59.94）时，根据工作流要求确保正确设置跳帧。

  5. 验证用户输入：使用 try-except 块优雅地捕获和处理时码错误：

    from dftt_timecode.error import DfttTimecodeError

try:
    tc = DfttTimecode(user_input, 'auto', fps=24)
except DfttTimecodeError as e:
    print(f"Invalid timecode: {e}")

性能考虑#

该库在内部使用高精度 Fraction 存储时间戳，这确保了准确性，但可能比浮点运算慢。对于性能关键型应用：

  • 创建一次时码对象并重复使用

  • 尽可能使用帧计数操作（整数运算更快）

  • 如果需要重复进行相同的转换，请考虑缓存转换后的值