deepflow-engine 0.1.0__tar.gz

deepflow_engine-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: deepflow-engine
+Version: 0.1.0
+Summary: Automated frame-by-frame rendering and video synthesis for physics simulations and generative game shorts.
+Author: deependujha
+Author-email: deependujha <deependujha21@gmail.com>
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: moviepy>=2.2.1
+Requires-Dist: pygame>=2.6.1
+Requires-Dist: pytelegrambotapi>=4.32
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# DeepFlow-Engine

deepflow_engine-0.1.0/README.md

@@ -0,0 +1 @@
+# DeepFlow-Engine

deepflow_engine-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+build-backend = "uv_build"
+requires = [ "uv-build>=0.10.8,<0.11" ]
+
+[project]
+name = "deepflow-engine"
+version = "0.1.0"
+
+description = "Automated frame-by-frame rendering and video synthesis for physics simulations and generative game shorts."
+readme = "README.md"
+authors = [
+  { name = "deependujha", email = "deependujha21@gmail.com" },
+]
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "moviepy>=2.2.1",
+  "pygame>=2.6.1",
+  "pytelegrambotapi>=4.32",
+]
+scripts.deepflow-engine = "deepflow_engine:main"
+scripts.deepflow_engine = "deepflow_engine:main"
+
+[dependency-groups]
+dev = [
+  "pre-commit>=4.5.1",
+]

deepflow_engine-0.1.0/src/deepflow_engine/__init__.py

@@ -0,0 +1,21 @@
+# credits: https://github.com/deependujha
+
+# from deepflow_engine.publisher.telegram import TelegramPublisher
+# from deepflow_engine.renderer import video_renderer
+
+
+def main() -> None:
+    # publisher = TelegramPublisher()
+    # publisher.publish(
+    #     "DeepFlow-Engine_sample.mp4", {"description": "A video generated by DeepFlow-Engine!"}
+    # )
+    # video_renderer(
+    #     output_filename="DeepFlow-Engine_sample.mp4",
+    #     frames_dir="silence/frames",
+    #     collisions_log="silence/collisions_log.json",
+    #     audio_dict={"crash": "silence/game-over.mp3"},
+    # )
+    print("Hello from DeepFlow-Engine!")
+
+
+def pipeline() -> None: ...

deepflow_engine-0.1.0/src/deepflow_engine/collisions.py

@@ -0,0 +1,17 @@
+# credits: https://github.com/deependujha
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Event:
+    # Example:
+    #   {
+    #     "frame": 143,
+    #     "time": 2.3833333333333333,
+    #     "type": "crash"
+    #   }
+
+    frame: int
+    time: float
+    type: str

deepflow_engine-0.1.0/src/deepflow_engine/constants.py

@@ -0,0 +1,17 @@
+# credits: https://github.com/deependujha
+
+# Creating colors
+BLUE = (0, 0, 255)
+RED = (255, 0, 0)
+GREEN = (0, 255, 0)
+BLACK = (0, 0, 0)
+WHITE = (255, 255, 255)
+
+DEFAULT_GAME_WIDTH = 360
+DEFAULT_GAME_HEIGHT = 640  # still 9:16
+
+DEFAULT_WINDOW_WIDTH = 720
+DEFAULT_WINDOW_HEIGHT = 1280
+
+# --- PYGAME DEFAULT CONSTANTS ---
+DEFAULT_FPS = 60

deepflow_engine-0.1.0/src/deepflow_engine/errors/__init__.py

@@ -0,0 +1,26 @@
+# credits: https://github.com/deependujha
+
+
+class BaseError(Exception):
+    """Base class for all DeepFlow-Engine exceptions."""
+
+    pass
+
+
+class RendererError(BaseError):
+    """Base class for all renderer-related exceptions."""
+
+    def __init__(self, message: str) -> None:
+        _base_msg = "An error occurred in the renderer: "
+        super().__init__(_base_msg + message)
+
+
+class PublisherError(BaseError):
+    """Base class for all publisher-related exceptions."""
+
+    def __init__(self, message: str) -> None:
+        _base_msg = "An error occurred in the publisher: "
+        super().__init__(_base_msg + message)
+
+
+__all__ = ["BaseError", "RendererError", "PublisherError"]

deepflow_engine-0.1.0/src/deepflow_engine/game.py

@@ -0,0 +1,121 @@
+# credits: https://github.com/deependujha
+
+from abc import ABC, abstractmethod
+
+import pygame
+import sys
+from typing import override
+
+from deepflow_engine.constants import (
+    DEFAULT_FPS,
+    DEFAULT_GAME_HEIGHT,
+    DEFAULT_GAME_WIDTH,
+    WHITE,
+)
+
+
+class BaseGame(ABC):
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def start(self) -> None:
+        pass
+
+    @abstractmethod
+    def exit(self) -> None:
+        pass
+
+    @abstractmethod
+    def handle_events(self) -> None:
+        pass
+
+    @abstractmethod
+    def update(self) -> None:
+        pass
+
+    @abstractmethod
+    def render(self) -> None:
+        pass
+
+    @abstractmethod
+    def loop(self) -> None:
+        pass
+
+
+class DeepFlowEngineGame(BaseGame):
+    def __init__(
+        self,
+        *,
+        fps: int = DEFAULT_FPS,
+        caption: str = "DeepFlow-Engine",
+        display_surface_width: int = DEFAULT_GAME_WIDTH,
+        display_surface_height: int = DEFAULT_GAME_HEIGHT,
+        display_surface_fill_color: tuple[int, int, int] = WHITE,
+    ) -> None:
+        super().__init__()
+        self._running = False
+        self.fps = fps
+        self.FramePerSec = pygame.time.Clock()
+        self.caption = caption
+        self.display_surface_width = display_surface_width
+        self.display_surface_height = display_surface_height
+        self.display_surface_fill_color = display_surface_fill_color
+        self.dt = 0.0
+        self._sprite_groups = {}
+        self._added_sprites = set()
+
+    def _verify_all_sprites_are_part_of_a_group(self) -> None:
+        for attribute, value in vars(self).items():
+            if (
+                isinstance(value, pygame.sprite.Sprite)
+                and value not in self._added_sprites
+            ):
+                raise ValueError(
+                    f"Sprite '{attribute}' is not part of any sprite group. Please add it to a sprite group using 'add_to_sprite_group' method."
+                )
+
+    def add_to_sprite_group(
+        self, group_name: str, sprite: pygame.sprite.Sprite
+    ) -> None:
+        if group_name not in self._sprite_groups:
+            self._sprite_groups[group_name] = pygame.sprite.Group()
+        self._sprite_groups[group_name].add(sprite)
+        self._added_sprites.add(sprite)
+
+    def get_sprite_group(self, group_name: str) -> pygame.sprite.Group:
+        return self._sprite_groups.get(group_name, pygame.sprite.Group())
+
+    @override
+    def start(self) -> None:
+        self._verify_all_sprites_are_part_of_a_group()
+        pygame.init()
+        self._running = True
+        self.display_surface = pygame.display.set_mode(
+            (self.display_surface_width, self.display_surface_height)
+        )
+        self.display_surface.fill(self.display_surface_fill_color)
+        pygame.display.set_caption(self.caption)
+
+    @override
+    def loop(self) -> None:
+        while self._running:
+            self.handle_events()
+            self.update()
+            self.render()
+            # self.dt = self.FramePerSec.tick(self.fps) / 1000.0
+            self.FramePerSec.tick(self.fps)
+            self.dt = 1.0 / self.fps
+
+    @override
+    def render(self) -> None:
+        pygame.display.update()
+
+    @override
+    def exit(self) -> None:
+        # kill all sprites in the groups
+        for group in self._sprite_groups.values():
+            for sprite in group:
+                sprite.kill()
+        pygame.quit()
+        sys.exit()

deepflow_engine-0.1.0/src/deepflow_engine/publisher/__init__.py

@@ -0,0 +1,6 @@
+# credits: https://github.com/deependujha
+
+from deepflow_engine.publisher.base import BasePublisher
+from deepflow_engine.publisher.telegram import TelegramPublisher
+
+__all__ = ["BasePublisher", "TelegramPublisher"]

deepflow_engine-0.1.0/src/deepflow_engine/publisher/base.py

@@ -0,0 +1,33 @@
+# credits: https://github.com/deependujha
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from deepflow_engine.errors import PublisherError
+
+
+@dataclass
+class VideoMetadata:
+    description: str
+    tags: list[str]
+
+
+class BasePublisher(ABC):
+    def __init__(self) -> None:
+        pass
+
+    def parse_metadata(self, metadata: VideoMetadata) -> str:
+        components = [f"Description: {metadata.description}"]
+        if metadata.tags:
+            components.append(f"Tags: {', '.join(metadata.tags)}")
+        return "\n".join(components)
+
+    @abstractmethod
+    def _publish(self, filename: str, msg: str) -> None:
+        pass
+
+    def publish(self, filename: str, metadata: VideoMetadata) -> None:
+        try:
+            parsed_metadata = self.parse_metadata(metadata)
+            self._publish(filename, parsed_metadata)
+        except Exception as e:
+            raise PublisherError(str(e)) from e

deepflow_engine-0.1.0/src/deepflow_engine/publisher/telegram.py

@@ -0,0 +1,17 @@
+# credits: https://github.com/deependujha
+
+import telebot
+from typing import override
+from deepflow_engine.publisher.base import BasePublisher
+
+
+class TelegramPublisher(BasePublisher):
+    def __init__(self) -> None:
+        self._bot = telebot.TeleBot("8243264320:AAE_dZ-zje2lkKGeaqW3P5Z0Cp2vrITepcs")
+        self._chat_id = "-1003780272239"  # oddly_realm group
+
+    @override
+    def _publish(self, filename: str, msg: str) -> None:
+        video = open(filename, "rb")
+        self._bot.send_video(chat_id=self._chat_id, video=video, caption=msg)
+        video.close()

deepflow_engine-0.1.0/src/deepflow_engine/renderer.py

@@ -0,0 +1,254 @@
+# credits: https://github.com/deependujha
+
+import json
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+from deepflow_engine.errors import RendererError
+from deepflow_engine.collisions import Event
+from deepflow_engine.constants import DEFAULT_FPS
+
+
+# ----------------------------
+# Frame Sorting
+# ----------------------------
+def get_sorted_base_frames(frames_dir: Path) -> list[Path]:
+    pattern = re.compile(r"^frame_(\d+)(?:_pause_(\d+))?\.png$")
+    frames = []
+
+    for f in frames_dir.iterdir():
+        m = pattern.match(f.name)
+        if m:
+            frame_num = int(m.group(1))
+            pause_num = int(m.group(2)) if m.group(2) is not None else -1
+            frames.append((frame_num, pause_num, f))
+
+    frames.sort(key=lambda x: (x[0], x[1]))
+    return [f for _, _, f in frames]
+
+
+# ----------------------------
+# Load Events
+# ----------------------------
+def load_collisions(log_path: Path) -> set[Event]:
+    if not log_path.exists():
+        raise RendererError(f"{log_path} not found.")
+
+    with open(log_path) as fh:
+        data = json.load(fh)
+
+    return {Event(**entry) for entry in data}
+
+
+# ----------------------------
+# Validation
+# ----------------------------
+def validate_audio_dict(audio_dict: dict[str, Path]) -> None:
+    for event_type, path in audio_dict.items():
+        if not path.exists():
+            raise RendererError(
+                f"Audio file for event '{event_type}' not found: {path}"
+            )
+
+
+def validate_event_audio_mapping(
+    events: set[Event], audio_dict: dict[str, Path]
+) -> None:
+    missing = {event.type for event in events if event.type not in audio_dict}
+
+    if missing:
+        raise RendererError(
+            f"Missing audio mapping for event types: {sorted(missing)}.\n"
+            f"Provided mappings: {list(audio_dict.keys())}"
+        )
+
+
+# ----------------------------
+# Build Frame Sequence
+# ----------------------------
+def build_frame_sequence(
+    base_frames: list[Path],
+    collision_frames: set[int],
+    pause_extra: int = 10,
+) -> list[Path]:
+    sequence = []
+    frame_pattern = re.compile(r"^frame_(\d+)")
+
+    for frame_path in base_frames:
+        m = frame_pattern.match(frame_path.name)
+        if not m:
+            raise RendererError(f"Invalid frame filename: {frame_path.name}")
+
+        frame_num = int(m.group(1))
+        sequence.append(frame_path)
+
+        if frame_num in collision_frames:
+            sequence.extend([frame_path] * pause_extra)
+
+    return sequence
+
+
+# ----------------------------
+# Write FFmpeg Concat List
+# ----------------------------
+def write_concat_list(sequence: list[Path], list_path: Path, FPS: int) -> None:
+    duration = 1.0 / FPS
+
+    with open(list_path, "w") as fh:
+        for frame_path in sequence:
+            fh.write(f"file '{frame_path.resolve()}'\n")
+            fh.write(f"duration {duration:.10f}\n")
+
+        fh.write(f"file '{sequence[-1].resolve()}'\n")
+
+
+# ----------------------------
+# FFmpeg Command Builder (Event-driven audio)
+# ----------------------------
+def build_ffmpeg_cmd(
+    concat_list: Path,
+    events: set[Event],
+    audio_dict: dict[str, Path],
+    video_duration: float,
+    output: Path,
+) -> list[str]:
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-f",
+        "concat",
+        "-safe",
+        "0",
+        "-i",
+        str(concat_list),
+    ]
+
+    # --- add audio inputs ---
+    audio_inputs = []
+    for event in events:
+        audio_path = audio_dict[event.type]
+        audio_inputs.append((event, audio_path))
+
+    for _, path in audio_inputs:
+        cmd += ["-i", str(path.resolve())]
+
+    # --- video encoding ---
+    cmd += [
+        "-fps_mode",
+        "passthrough",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:v",
+        "libx264",
+        "-crf",
+        "18",
+        "-preset",
+        "slow",
+    ]
+
+    # --- audio ---
+    if audio_inputs:
+        filter_parts = []
+        mix_inputs = []
+
+        for i, (event, _) in enumerate(audio_inputs):
+            delay_ms = int(event.time * 1000)
+            input_idx = i + 1
+
+            filter_parts.append(f"[{input_idx}:a]adelay={delay_ms}|{delay_ms}[a{i}]")
+            mix_inputs.append(f"[a{i}]")
+
+        filter_complex = (
+            ";".join(filter_parts) + f";{''.join(mix_inputs)}"
+            f"amix=inputs={len(mix_inputs)}:duration=longest:normalize=1,"
+            f"apad,atrim=duration={video_duration:.6f}[a]"
+        )
+
+        cmd += [
+            "-filter_complex",
+            filter_complex,
+            "-map",
+            "0:v:0",
+            "-map",
+            "[a]",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "192k",
+            "-ar",
+            "44100",
+        ]
+
+    cmd.append(str(output))
+    return cmd
+
+
+# ----------------------------
+# Main Renderer
+# ----------------------------
+def video_renderer(
+    output_filename: str | Path,
+    frames_dir: str | Path,
+    collisions_log: str | Path,
+    audio_dict: dict[str, str | Path],
+    FPS: int = DEFAULT_FPS,
+) -> Path:
+    """Generate video from frames + event timeline + audio mapping."""
+
+    frames_dir = Path(frames_dir)
+    collisions_log = Path(collisions_log)
+    output_video = Path(output_filename)
+    audio_dict = {k: Path(v) for k, v in audio_dict.items()}
+
+    if not frames_dir.exists():
+        raise RendererError(f"frames directory '{frames_dir}' not found.")
+
+    base_frames = get_sorted_base_frames(frames_dir)
+    if not base_frames:
+        raise RendererError("no frames found.")
+
+    # --- events ---
+    collisions = load_collisions(collisions_log)
+
+    # --- validation ---
+    validate_audio_dict(audio_dict)
+    validate_event_audio_mapping(collisions, audio_dict)
+
+    collision_frame_nums = {event.frame for event in collisions}
+
+    # --- build timeline ---
+    sequence = build_frame_sequence(base_frames, collision_frame_nums)
+
+    if not sequence:
+        raise RendererError("empty frame sequence.")
+
+    video_duration = len(sequence) / FPS
+
+    # --- concat file ---
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".txt", delete=False, prefix="ffmpeg_concat_"
+    ) as tmp:
+        concat_list = Path(tmp.name)
+
+    try:
+        write_concat_list(sequence, concat_list, FPS)
+
+        cmd = build_ffmpeg_cmd(
+            concat_list,
+            collisions,
+            audio_dict,
+            video_duration,
+            output_video,
+        )
+
+        result = subprocess.run(cmd, check=False)
+
+        if result.returncode != 0:
+            raise RendererError(f"ffmpeg failed with code {result.returncode}")
+
+        return output_video.resolve()
+
+    finally:
+        concat_list.unlink(missing_ok=True)

deepflow_engine-0.1.0/src/deepflow_engine/sample_game/__init__.py

@@ -0,0 +1 @@
+# credits: https://github.com/deependujha

deepflow_engine-0.1.0/src/deepflow_engine/sample_game/learning_pygame.py

@@ -0,0 +1,40 @@
+# credits: https://github.com/deependujha
+
+import pygame
+from deepflow_engine.game import DeepFlowEngineGame
+
+
+class SimplePyGame(DeepFlowEngineGame):
+    def __init__(self):
+        super().__init__()
+        # Initializing
+        pygame.init()
+
+        # Setting up FPS
+        self.FPS = 60
+        self.FramePerSec = pygame.time.Clock()
+
+        # Creating colors
+        self.BLUE = (0, 0, 255)
+        self.RED = (255, 0, 0)
+        self.GREEN = (0, 255, 0)
+        self.BLACK = (0, 0, 0)
+        self.WHITE = (255, 255, 255)
+
+        # Other Variables for use in the program
+        self.SCREEN_WIDTH = 400
+        self.SCREEN_HEIGHT = 600
+        self.SPEED = 7
+        self.SCORE = 0
+
+        # Setting up Fonts
+        self.font = pygame.font.SysFont("Verdana", 60)
+        self.font_small = pygame.font.SysFont("Verdana", 20)
+        self.game_over = self.font.render("Game Over", True, self.BLACK)
+
+        self.background = pygame.image.load("AnimatedStreet.png")
+
+        # Create a white screen
+        self.DISPLAYSURF = pygame.display.set_mode((400, 600))
+        self.DISPLAYSURF.fill(self.WHITE)
+        pygame.display.set_caption("Game")