beatfit 0.1.0__tar.gz

beatfit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

beatfit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddie Zhou
+
+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.

beatfit-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: beatfit
+Version: 0.1.0
+Summary: Retime video clips so chosen moments land on the beats of a song.
+Project-URL: Homepage, https://github.com/TwelveNights/beatfit
+Project-URL: Issues, https://github.com/TwelveNights/beatfit/issues
+Author: Eddie Zhou
+License-Expression: MIT
+License-File: LICENSE
+Keywords: beat,editing,ffmpeg,montage,music,retiming,video
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# beatfit
+
+Retime a video clip to fill part of a song so that chosen moments in it land on beats.
+
+You give it the moments (as source frames), the song's beat times and the stretch of the
+song the clip has to fill. It returns the clip as a list of constant-speed pieces.
+
+Footage plays in real time unless the gap between two moments is longer than 5.5 s. Then
+the middle of the gap is sped up to at most 1.5x, with short eased ramps and about a second
+of real time either side of each moment. The lead-in is picked so the first moment falls on
+a beat, a downbeat if possible, and each sped-up gap gets whatever length puts the next
+moment on a beat. If a gap is still too long, its sped-up middle gets a jump cut. With the
+default settings that happens to every gap long enough to speed up; raise `max_gap_out` to
+speed up without cutting. Ranges you mark as protected are never sped up or cut.
+
+The result fills the requested number of frames exactly and never plays slower than real
+time or faster than `max_speed`.
+
+beatfit doesn't analyse audio. Use a beat tracker such as
+[beat_this](https://github.com/CPJKU/beat_this), [All-In-One](https://github.com/mir-aidj/all-in-one)
+or [librosa](https://librosa.org) for beats and downbeats. It also doesn't decide which clip
+goes where in the song; `fit_clip` returns `None` when a clip can't fill a slot, so you can
+try clips against slots and keep the ones that fit.
+
+Pure Python with no dependencies, 3.10 or newer.
+
+## Example
+
+```python
+from beatfit import Clip, Event, Params, fit_clip
+
+fps = 60
+beats = [0.5 + 0.5 * k for k in range(200)]  # 120 BPM, from your beat tracker (seconds)
+downbeats = beats[::4]
+
+# moments at 12.0 s, 13.1 s and 31.5 s of the recording (source frames at `fps`)
+clip = Clip(
+    events=[Event(12 * fps), Event(round(13.1 * fps)), Event(round(31.5 * fps), protect=(4.0, 1.0))],
+    src_start=0,             # usable footage
+    src_end=40 * fps,
+)
+start = round(downbeats[4] * fps)          # fill bars 4-12 of the song
+frames = round(downbeats[12] * fps) - start
+fit = fit_clip(clip, start, frames, beats, downbeats, Params(fps=fps))
+
+for p in fit.pieces:  # constant-speed pieces: source frames -> output frames
+    print(p.src, p.src_frames, p.out_frames, round(p.speed, 3), "jump" if p.jump else "")
+print(fit.event_out, fit.event_on_beat, fit.event_err_ms)
+```
+
+To render it with ffmpeg (video only):
+
+```python
+import subprocess
+from beatfit.ffmpeg import command
+
+subprocess.run(command("recording.mp4", fit.pieces, fps, "clip.mp4"), check=True)
+```
+
+`beatfit.ffmpeg.filter_graph` and `input_args` return the parts of that command, for use
+in a larger filter graph.
+
+## Concepts
+
+All times are integer frames at `Params.fps` (default 60) on two timelines: source (the
+recording) and output (the song). Beats are in seconds on the output timeline. A source
+frame is `1 / fps` seconds whatever the recording's own frame rate, so a 30 fps recording
+works with `fps=60`.
+
+A `Clip` has `events` in increasing source order and the usable source range
+`[src_start, src_end)`. Optional fields:
+
+| Field | Meaning |
+|---|---|
+| `lead_from` | Start the lead-in here, e.g. where the tension begins. A long wait is sped up after a moment of real time. |
+| `lead` | `Lead(pref_min, pref_max, max_realtime, hold)`: preferred lead-in length in seconds, the longest lead-in played entirely in real time, and the real time kept before the first event when the lead-in is longer than that. |
+| `tail_min` | Frames of real time after the last event, e.g. for a reaction. The tail then ends on a bar line, up to `tail_slack_bars` later. |
+| `protect` | Source ranges `[start, end)` that always play in real time. |
+
+`Event.protect = (before, after)` protects that many seconds around one event.
+`Event.soft` marks an event whose timing is approximate, so putting it on a beat is
+optional.
+
+A protected range between two events is always shown in real time, and the dead time on
+either side of it can still be sped up or cut. A range around the first event is shown from
+its start: the clip never begins inside it, and the lead-in stays in real time as long as
+the range needs. A range earlier than that is shown only if the lead-in reaches back to it.
+A clip can end before a range around its last event is over.
+
+`Params` holds the other settings: real time around events (`pre_hold`, `post_hold`), the
+speed cap (`max_speed`), the shortest gap that gets sped up (`speed_gap`), the longest
+sped-up stretch before a jump cut (`max_gap_out`), lead-in and tail limits, and
+`beats_per_bar`. `last=True` allows a longer tail for the final clip of a song, and
+`music_end` penalises events that would land after the music stops.
+
+A `Fit` has the `pieces`; each event's output frame relative to the slot (`event_out`);
+whether it is on a beat or downbeat and how far it is from the nearest beat
+(`event_err_ms`); and `max_speed`, `jumps`, `lead_out`, `tail_out` and `cost`. `locate`
+and `source_at` convert between the two timelines.
+
+## How it works
+
+A dynamic program over (event, landing frame), where landing frames are the beats inside
+the slot. Gaps shorter than `speed_gap` play in real time, so the event after one lands
+wherever that puts it; the solver favours lead-ins that bring those events close to a beat.
+A speed-up is up to three eased steps on each side of a constant plateau, so renderers and
+editors only ever see constant speeds.
+
+## Limits
+
+- It fits one clip into one slot. Choosing and ordering clips is up to you.
+- Times are whole frames, so an event lands within half a frame of its beat (8 ms at 60 fps).
+- The ffmpeg helper renders video only. Retiming or muting the audio is up to you.
+- It was written for game highlight montages at 60 fps. Other footage and tempos have only
+  been tested with synthetic data.
+
+## Related work
+
+- [visbeat](https://github.com/abedavis/visbeat) (Davis & Agrawala, "Visual Rhythm and
+  Beat", SIGGRAPH 2018) warps video so visible motion lines up with musical beats. beatfit
+  takes the moments as given and keeps real time around them.
+- [mugen](https://github.com/scherroman/mugen) and similar tools cut video to the beat.
+  They put cuts on beats rather than moving moments inside a clip.
+- [otio-music-arrangement](https://pypi.org/project/otio-music-arrangement/) builds
+  beat-aligned OpenTimelineIO timelines from placeholder clips.
+
+## License
+
+MIT

beatfit-0.1.0/README.md

@@ -0,0 +1,129 @@
+# beatfit
+
+Retime a video clip to fill part of a song so that chosen moments in it land on beats.
+
+You give it the moments (as source frames), the song's beat times and the stretch of the
+song the clip has to fill. It returns the clip as a list of constant-speed pieces.
+
+Footage plays in real time unless the gap between two moments is longer than 5.5 s. Then
+the middle of the gap is sped up to at most 1.5x, with short eased ramps and about a second
+of real time either side of each moment. The lead-in is picked so the first moment falls on
+a beat, a downbeat if possible, and each sped-up gap gets whatever length puts the next
+moment on a beat. If a gap is still too long, its sped-up middle gets a jump cut. With the
+default settings that happens to every gap long enough to speed up; raise `max_gap_out` to
+speed up without cutting. Ranges you mark as protected are never sped up or cut.
+
+The result fills the requested number of frames exactly and never plays slower than real
+time or faster than `max_speed`.
+
+beatfit doesn't analyse audio. Use a beat tracker such as
+[beat_this](https://github.com/CPJKU/beat_this), [All-In-One](https://github.com/mir-aidj/all-in-one)
+or [librosa](https://librosa.org) for beats and downbeats. It also doesn't decide which clip
+goes where in the song; `fit_clip` returns `None` when a clip can't fill a slot, so you can
+try clips against slots and keep the ones that fit.
+
+Pure Python with no dependencies, 3.10 or newer.
+
+## Example
+
+```python
+from beatfit import Clip, Event, Params, fit_clip
+
+fps = 60
+beats = [0.5 + 0.5 * k for k in range(200)]  # 120 BPM, from your beat tracker (seconds)
+downbeats = beats[::4]
+
+# moments at 12.0 s, 13.1 s and 31.5 s of the recording (source frames at `fps`)
+clip = Clip(
+    events=[Event(12 * fps), Event(round(13.1 * fps)), Event(round(31.5 * fps), protect=(4.0, 1.0))],
+    src_start=0,             # usable footage
+    src_end=40 * fps,
+)
+start = round(downbeats[4] * fps)          # fill bars 4-12 of the song
+frames = round(downbeats[12] * fps) - start
+fit = fit_clip(clip, start, frames, beats, downbeats, Params(fps=fps))
+
+for p in fit.pieces:  # constant-speed pieces: source frames -> output frames
+    print(p.src, p.src_frames, p.out_frames, round(p.speed, 3), "jump" if p.jump else "")
+print(fit.event_out, fit.event_on_beat, fit.event_err_ms)
+```
+
+To render it with ffmpeg (video only):
+
+```python
+import subprocess
+from beatfit.ffmpeg import command
+
+subprocess.run(command("recording.mp4", fit.pieces, fps, "clip.mp4"), check=True)
+```
+
+`beatfit.ffmpeg.filter_graph` and `input_args` return the parts of that command, for use
+in a larger filter graph.
+
+## Concepts
+
+All times are integer frames at `Params.fps` (default 60) on two timelines: source (the
+recording) and output (the song). Beats are in seconds on the output timeline. A source
+frame is `1 / fps` seconds whatever the recording's own frame rate, so a 30 fps recording
+works with `fps=60`.
+
+A `Clip` has `events` in increasing source order and the usable source range
+`[src_start, src_end)`. Optional fields:
+
+| Field | Meaning |
+|---|---|
+| `lead_from` | Start the lead-in here, e.g. where the tension begins. A long wait is sped up after a moment of real time. |
+| `lead` | `Lead(pref_min, pref_max, max_realtime, hold)`: preferred lead-in length in seconds, the longest lead-in played entirely in real time, and the real time kept before the first event when the lead-in is longer than that. |
+| `tail_min` | Frames of real time after the last event, e.g. for a reaction. The tail then ends on a bar line, up to `tail_slack_bars` later. |
+| `protect` | Source ranges `[start, end)` that always play in real time. |
+
+`Event.protect = (before, after)` protects that many seconds around one event.
+`Event.soft` marks an event whose timing is approximate, so putting it on a beat is
+optional.
+
+A protected range between two events is always shown in real time, and the dead time on
+either side of it can still be sped up or cut. A range around the first event is shown from
+its start: the clip never begins inside it, and the lead-in stays in real time as long as
+the range needs. A range earlier than that is shown only if the lead-in reaches back to it.
+A clip can end before a range around its last event is over.
+
+`Params` holds the other settings: real time around events (`pre_hold`, `post_hold`), the
+speed cap (`max_speed`), the shortest gap that gets sped up (`speed_gap`), the longest
+sped-up stretch before a jump cut (`max_gap_out`), lead-in and tail limits, and
+`beats_per_bar`. `last=True` allows a longer tail for the final clip of a song, and
+`music_end` penalises events that would land after the music stops.
+
+A `Fit` has the `pieces`; each event's output frame relative to the slot (`event_out`);
+whether it is on a beat or downbeat and how far it is from the nearest beat
+(`event_err_ms`); and `max_speed`, `jumps`, `lead_out`, `tail_out` and `cost`. `locate`
+and `source_at` convert between the two timelines.
+
+## How it works
+
+A dynamic program over (event, landing frame), where landing frames are the beats inside
+the slot. Gaps shorter than `speed_gap` play in real time, so the event after one lands
+wherever that puts it; the solver favours lead-ins that bring those events close to a beat.
+A speed-up is up to three eased steps on each side of a constant plateau, so renderers and
+editors only ever see constant speeds.
+
+## Limits
+
+- It fits one clip into one slot. Choosing and ordering clips is up to you.
+- Times are whole frames, so an event lands within half a frame of its beat (8 ms at 60 fps).
+- The ffmpeg helper renders video only. Retiming or muting the audio is up to you.
+- It was written for game highlight montages at 60 fps. Other footage and tempos have only
+  been tested with synthetic data.
+
+## Related work
+
+- [visbeat](https://github.com/abedavis/visbeat) (Davis & Agrawala, "Visual Rhythm and
+  Beat", SIGGRAPH 2018) warps video so visible motion lines up with musical beats. beatfit
+  takes the moments as given and keeps real time around them.
+- [mugen](https://github.com/scherroman/mugen) and similar tools cut video to the beat.
+  They put cuts on beats rather than moving moments inside a clip.
+- [otio-music-arrangement](https://pypi.org/project/otio-music-arrangement/) builds
+  beat-aligned OpenTimelineIO timelines from placeholder clips.
+
+## License
+
+MIT

beatfit-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "beatfit"
+version = "0.1.0"
+description = "Retime video clips so chosen moments land on the beats of a song."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Eddie Zhou" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["video", "music", "beat", "montage", "editing", "retiming", "ffmpeg"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+
+[project.urls]
+Homepage = "https://github.com/TwelveNights/beatfit"
+Issues = "https://github.com/TwelveNights/beatfit/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beatfit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 130
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.ruff.lint]
+# int() around round()/floor() is deliberate: inputs may be numpy floats (beats from a tracker)
+# zip(xs, xs[1:]) for successive pairs is fine
+ignore = ["RUF046", "RUF007"]

beatfit-0.1.0/src/beatfit/__init__.py

@@ -0,0 +1,23 @@
+"""Retime video clips so chosen moments land on the beats of a song."""
+
+from .fit import Clip, Event, Fit, Lead, Params, Piece, fit_clip, locate, protected, realtime_ok, source_at
+from .ramp import max_src, min_out, ramp
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Clip",
+    "Event",
+    "Fit",
+    "Lead",
+    "Params",
+    "Piece",
+    "fit_clip",
+    "locate",
+    "max_src",
+    "min_out",
+    "protected",
+    "ramp",
+    "realtime_ok",
+    "source_at",
+]

beatfit-0.1.0/src/beatfit/ffmpeg.py

@@ -0,0 +1,98 @@
+"""Render a fit with ffmpeg: one input per continuous stretch (split at jump cuts), each
+retimed with a piecewise-linear ``setpts``, resampled to a constant frame rate and
+concatenated. Video only: retiming audio is left to the caller."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .fit import Piece
+
+
+@dataclass
+class Segment:
+    """A continuous stretch of source (no jump cut inside)."""
+
+    pieces: list[Piece]
+
+    @property
+    def src(self) -> int:
+        return self.pieces[0].src
+
+    @property
+    def src_frames(self) -> int:
+        return sum(p.src_frames for p in self.pieces)
+
+    @property
+    def out_frames(self) -> int:
+        return sum(p.out_frames for p in self.pieces)
+
+
+def segments(pieces: list[Piece]) -> list[Segment]:
+    """Split pieces at jump cuts (and anywhere else the source is not continuous)."""
+    out: list[Segment] = []
+    for pc in pieces:
+        if out and not pc.jump and out[-1].pieces[-1].src_end == pc.src:
+            out[-1].pieces.append(pc)
+        else:
+            out.append(Segment([pc]))
+    return out
+
+
+def _num(x: float) -> str:
+    return f"{x:.9f}".rstrip("0").rstrip(".") if x != int(x) else str(int(x))
+
+
+def setpts_expr(pieces: list[Piece], fps: float) -> str:
+    """Expression mapping segment-relative source time ``T`` (seconds) to output seconds."""
+    terms = []
+    a = 0
+    for p in pieces:
+        terms.append(f"clip(T-{_num(a / fps)},0,{_num(p.src_frames / fps)})*{_num(p.out_frames / p.src_frames)}")
+        a += p.src_frames
+    return "+".join(terms)
+
+
+def filter_graph(pieces: list[Piece], fps: float, out_label: str = "v") -> str:
+    """``-filter_complex`` graph for the inputs made by :func:`input_args` (input k is
+    segment k), ending in ``[out_label]``."""
+    segs = segments(pieces)
+    chains = []
+    for k, seg in enumerate(segs):
+        ch = f"[{k}:v:0]setpts=PTS-STARTPTS"
+        if any(p.src_frames != p.out_frames for p in seg.pieces):
+            ch += f",setpts='({setpts_expr(seg.pieces, fps)})/TB'"
+        # a constant frame rate, padded and trimmed to exactly the planned number of frames
+        ch += f",fps=fps={_num(fps)},tpad=stop_mode=clone:stop=8,trim=end_frame={seg.out_frames},setpts=PTS-STARTPTS[s{k}]"
+        chains.append(ch)
+    chains.append("".join(f"[s{k}]" for k in range(len(segs))) + f"concat=n={len(segs)}:v=1:a=0[{out_label}]")
+    return ";\n".join(chains)
+
+
+def input_args(source: str, pieces: list[Piece], fps: float) -> list[str]:
+    """``-ss``/``-t``/``-i`` arguments, one input per segment. Source frames are taken to be
+    ``1 / fps`` seconds from the start of the file, whatever its own frame rate."""
+    args: list[str] = []
+    for seg in segments(pieces):
+        args += ["-ss", _num(seg.src / fps), "-t", _num((seg.src_frames + 2) / fps), "-i", source]
+    return args
+
+
+def command(
+    source: str, pieces: list[Piece], fps: float, output: str, ffmpeg: str = "ffmpeg", encode: list[str] | None = None
+) -> list[str]:
+    """A complete ffmpeg command rendering the pieces of ``source`` to ``output`` (no audio)."""
+    enc = encode if encode is not None else ["-c:v", "libx264", "-crf", "18", "-pix_fmt", "yuv420p"]
+    return [
+        ffmpeg,
+        "-hide_banner",
+        "-y",
+        *input_args(source, pieces, fps),
+        "-filter_complex",
+        filter_graph(pieces, fps),
+        "-map",
+        "[v]",
+        "-an",
+        *enc,
+        output,
+    ]