preroll 0.0.1__py3-none-any.whl

preroll/__init__.py

@@ -0,0 +1,17 @@
+"""preroll: tools for editing video podcasts. This early release holds the timecode helpers."""
+from .timecode import (
+    frame_rate,
+    frames_to_seconds,
+    frames_to_timecode,
+    seconds_to_frames,
+    timecode_to_frames,
+)
+
+__version__ = "0.0.1"
+__all__ = [
+    "frame_rate",
+    "frames_to_seconds",
+    "frames_to_timecode",
+    "seconds_to_frames",
+    "timecode_to_frames",
+]

preroll/timecode.py

@@ -0,0 +1,106 @@
+"""Frame counts, seconds and SMPTE timecode.
+
+A timecode is HH:MM:SS:FF. Drop-frame timecode (29.97 and 59.94 frames a second) is written with a semicolon before
+the frames, HH:MM:SS;FF. It skips frame numbers, never frames: the first 2 numbers (4 at 59.94) of each minute are
+left out, except in each tenth minute, so that the timecode keeps step with the clock.
+"""
+from fractions import Fraction
+
+_NTSC = {
+    Fraction("23.976"): Fraction(24000, 1001),
+    Fraction("23.98"): Fraction(24000, 1001),
+    Fraction("29.97"): Fraction(30000, 1001),
+    Fraction("47.952"): Fraction(48000, 1001),
+    Fraction("59.94"): Fraction(60000, 1001),
+    Fraction("119.88"): Fraction(120000, 1001),
+}
+
+
+def frame_rate(fps):
+    """The exact frame rate as a Fraction. fps: a number (24, 25, 29.97), a Fraction, or text ("30000/1001",
+    "23.976"). The NTSC rates given as decimals are read as their exact values (29.97 is 30000/1001)."""
+    if isinstance(fps, bool):
+        raise TypeError("frame rate must be a number, a Fraction or text")
+    try:
+        rate = Fraction(str(fps)) if isinstance(fps, float) else Fraction(fps)
+    except (TypeError, ValueError, ZeroDivisionError):
+        raise ValueError(f"not a frame rate: {fps!r}") from None
+    rate = _NTSC.get(rate, rate)
+    if rate <= 0:
+        raise ValueError(f"frame rate must be above 0, got {fps!r}")
+    return rate
+
+
+def _base(rate):
+    """The whole number of frame numbers in one timecode second (30 for 29.97)."""
+    return int(rate + Fraction(1, 2))
+
+
+def _drop(rate, drop_frame):
+    """Frame numbers skipped each minute: 2 at 29.97, 4 at 59.94, 0 for non-drop."""
+    can = rate in (Fraction(30000, 1001), Fraction(60000, 1001))
+    if drop_frame is None:
+        drop_frame = can
+    if drop_frame and not can:
+        raise ValueError("drop-frame timecode exists only for 29.97 and 59.94 frames a second")
+    return 2 * (_base(rate) // 30) if drop_frame else 0
+
+
+def frames_to_timecode(frames, fps, drop_frame=None):
+    """The timecode of a frame count (frame 0 is 00:00:00:00). drop_frame: None uses drop-frame at 29.97 and 59.94
+    and non-drop at every other rate."""
+    if isinstance(frames, bool) or not isinstance(frames, int):
+        raise TypeError("frames must be a whole number")
+    if frames < 0:
+        raise ValueError("frames must be 0 or more")
+    rate = frame_rate(fps)
+    base, drop = _base(rate), _drop(rate, drop_frame)
+    n = frames
+    if drop:
+        per_min = base * 60 - drop
+        per_10min = base * 600 - 9 * drop
+        tens, rest = divmod(frames, per_10min)
+        n += 9 * drop * tens
+        if rest >= base * 60:
+            n += drop * ((rest - base * 60) // per_min + 1)
+    ff = n % base
+    ss = n // base % 60
+    mm = n // (base * 60) % 60
+    hh = n // (base * 3600)
+    return f"{hh:02d}:{mm:02d}:{ss:02d}{';' if drop else ':'}{ff:02d}"
+
+
+def timecode_to_frames(timecode, fps, drop_frame=None):
+    """The frame count of a timecode. drop_frame: None reads the timecode's own mark (a semicolon or a full stop
+    before the frames means drop-frame)."""
+    if not isinstance(timecode, str):
+        raise TypeError("timecode must be text, for example '00:01:00;02'")
+    text = timecode.strip()
+    marked = len(text) > 3 and text[-3] in ";."
+    parts = text.replace(";", ":").replace(".", ":").split(":")
+    if len(parts) != 4 or not all(p.isdigit() for p in parts):
+        raise ValueError(f"not a timecode: {timecode!r} (expected HH:MM:SS:FF)")
+    hh, mm, ss, ff = (int(p) for p in parts)
+    rate = frame_rate(fps)
+    base = _base(rate)
+    drop = _drop(rate, marked if drop_frame is None else drop_frame)
+    if mm > 59 or ss > 59 or ff >= base:
+        raise ValueError(f"not a timecode at {base} frames a second: {timecode!r}")
+    if drop and ss == 0 and ff < drop and mm % 10:
+        raise ValueError(f"drop-frame timecode has no {timecode!r}: frame numbers 0 to {drop - 1} are skipped "
+                         "at the start of each minute, except each tenth minute")
+    minutes = 60 * hh + mm
+    return (minutes * 60 + ss) * base + ff - drop * (minutes - minutes // 10)
+
+
+def frames_to_seconds(frames, fps):
+    """The real time of a frame count, in seconds (240 frames at 23.976 are 10.01 s)."""
+    return float(frames / frame_rate(fps))
+
+
+def seconds_to_frames(seconds, fps):
+    """The frame that is on screen at a time in seconds (the last frame that starts at or before it)."""
+    if seconds < 0:
+        raise ValueError("seconds must be 0 or more")
+    value = Fraction(str(seconds)) if isinstance(seconds, float) else Fraction(seconds)
+    return int(value * frame_rate(fps))

preroll-0.0.1.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: preroll
+Version: 0.0.1
+Summary: Tools for editing video podcasts. This early release holds the timecode helpers.
+Author: preroll
+License-Expression: MIT
+License-File: LICENSE
+Keywords: drop-frame,editing,podcast,smpte,timecode,video
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# preroll
+
+Tools for editing video podcasts.
+
+This is an early release. It holds one part: timecode helpers that convert between frame counts, seconds and SMPTE
+timecode, with drop-frame timecode for 29.97 and 59.94 frames a second. More tools follow.
+
+## Install
+
+```
+pip install preroll
+```
+
+## Use
+
+```python
+from preroll import frames_to_timecode, timecode_to_frames, frames_to_seconds
+
+frames_to_timecode(1800, 29.97)                      # '00:01:00;02' (drop-frame is the default at 29.97)
+frames_to_timecode(1800, 29.97, drop_frame=False)    # '00:01:00:00'
+timecode_to_frames("01:00:00;00", 29.97)             # 107892
+timecode_to_frames("00:00:10:00", "24000/1001")      # 240
+frames_to_seconds(240, "24000/1001")                 # 10.01
+```
+
+A frame rate can be a number (`24`, `25`, `29.97`, `23.976`) or an exact fraction as text (`"30000/1001"`). The
+common NTSC rates given as decimals (23.976, 29.97, 59.94) are read as their exact fractions.
+
+## Licence
+
+MIT

preroll-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+preroll/__init__.py,sha256=PdSbNJ32McJwXupLqjuAhQY74Nn0Gnp8-MPvmByM4lA,389
+preroll/timecode.py,sha256=bTMSdXKkGf4NQJE0FOJTdVeazbD0ZKabeGioMYbJNUw,4631
+preroll-0.0.1.dist-info/METADATA,sha256=jxZ4LN64DrwgThc8vwlWNhDQ2v9sJS6yBvzf-7uqT3Y,1489
+preroll-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+preroll-0.0.1.dist-info/licenses/LICENSE,sha256=Uu5Y0z9fboL2smvR3gya2P3zSXUwSwtZ3M5AK4V9Ykk,1064
+preroll-0.0.1.dist-info/RECORD,,

preroll-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

preroll-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 preroll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.