preroll 0.0.1__tar.gz

preroll-0.0.1/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.

preroll-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,31 @@
+# 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/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "preroll"
+version = "0.0.1"
+description = "Tools for editing video podcasts. This early release holds the timecode helpers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "preroll" }]
+keywords = ["video", "podcast", "editing", "timecode", "smpte", "drop-frame"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/preroll"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]

preroll-0.0.1/src/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-0.0.1/src/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/tests/test_timecode.py

@@ -0,0 +1,67 @@
+from fractions import Fraction
+
+import pytest
+
+from preroll import (frame_rate, frames_to_seconds, frames_to_timecode, seconds_to_frames,
+                     timecode_to_frames)
+
+
+def test_frame_rate_reads_ntsc_decimals_as_exact_fractions():
+    assert frame_rate(29.97) == Fraction(30000, 1001)
+    assert frame_rate("23.976") == Fraction(24000, 1001)
+    assert frame_rate("24000/1001") == Fraction(24000, 1001)
+    assert frame_rate(25) == 25
+    with pytest.raises(ValueError):
+        frame_rate(0)
+    with pytest.raises(ValueError):
+        frame_rate("fast")
+
+
+def test_non_drop_timecode():
+    assert frames_to_timecode(0, 24) == "00:00:00:00"
+    assert frames_to_timecode(24, 23.976) == "00:00:01:00"
+    assert frames_to_timecode(25 * 3600 + 7, 25) == "01:00:00:07"
+    assert timecode_to_frames("00:00:10:00", "24000/1001") == 240
+    assert frames_to_timecode(1800, 29.97, drop_frame=False) == "00:01:00:00"
+
+
+def test_drop_frame_known_values():
+    assert frames_to_timecode(1799, 29.97) == "00:00:59;29"
+    assert frames_to_timecode(1800, 29.97) == "00:01:00;02"
+    assert frames_to_timecode(17981, 29.97) == "00:09:59;29"
+    assert frames_to_timecode(17982, 29.97) == "00:10:00;00"
+    assert frames_to_timecode(107892, 29.97) == "01:00:00;00"
+    assert frames_to_timecode(3600, 59.94) == "00:01:00;04"
+    assert timecode_to_frames("01:00:00;00", 29.97) == 107892
+    assert timecode_to_frames("00:01:00;02", "30000/1001") == 1800
+
+
+def test_drop_frame_mark_and_skipped_numbers():
+    assert timecode_to_frames("00:01:00:02", 29.97) == 1802             # no mark: read as non-drop
+    assert timecode_to_frames("00:01:00:02", 29.97, drop_frame=True) == 1800
+    with pytest.raises(ValueError):
+        timecode_to_frames("00:01:00;00", 29.97)                        # a skipped frame number
+    with pytest.raises(ValueError):
+        frames_to_timecode(10, 25, drop_frame=True)                     # no drop-frame at 25
+    with pytest.raises(ValueError):
+        timecode_to_frames("00:00:00:30", 29.97)
+
+
+@pytest.mark.parametrize("fps, drop", [(24, False), (25, False), (23.976, False), (29.97, True), (29.97, False),
+                                       (59.94, True), (30, False), (60, False)])
+def test_round_trip(fps, drop):
+    seen = None
+    for frames in list(range(0, 40000)) + [107891, 107892, 1078920, 2589407]:
+        tc = frames_to_timecode(frames, fps, drop_frame=drop)
+        assert timecode_to_frames(tc, fps, drop_frame=drop) == frames
+        if frames < 40000:
+            assert seen is None or tc > seen                            # timecodes rise with the frames
+            seen = tc
+
+
+def test_seconds():
+    assert frames_to_seconds(240, "24000/1001") == pytest.approx(10.01)
+    assert seconds_to_frames(10.01, 23.976) == 240
+    assert seconds_to_frames(1.0, 25) == 25
+    assert seconds_to_frames(0.999, 25) == 24
+    assert frames_to_seconds(107892, 29.97) == pytest.approx(3599.9964)   # one hour of drop-frame timecode