videopython 0.4.0__tar.gz → 0.5.0__tar.gz

videopython-0.5.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: videopython
+Version: 0.5.0
+Summary: Minimal video generation and processing library.
+Project-URL: Homepage, https://github.com/bartwojtowicz/videopython/
+Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
+Project-URL: Documentation, https://github.com/bartwojtowicz/videopython/
+Author-email: Bartosz Wójtowicz <bartoszwojtowicz@outlook.com>, Bartosz Rudnikowicz <bartoszrudnikowicz840@gmail.com>, Piotr Pukisz <piotr.pukisz@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,editing,generation,movie,opencv,python,shorts,video,videopython
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.10
+Requires-Dist: numpy>=1.25.2
+Requires-Dist: opencv-python>=4.9.0.80
+Requires-Dist: pillow>=10.3.0
+Requires-Dist: soundpython>=0.1.11
+Requires-Dist: tqdm>=4.66.3
+Provides-Extra: ai
+Requires-Dist: accelerate>=0.29.2; extra == 'ai'
+Requires-Dist: diffusers>=0.26.3; extra == 'ai'
+Requires-Dist: numba>=0.61.0; extra == 'ai'
+Requires-Dist: openai-whisper>=20240930; extra == 'ai'
+Requires-Dist: torch>=2.1.0; extra == 'ai'
+Requires-Dist: transformers>=4.38.1; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.14; extra == 'dev'
+Requires-Dist: types-pillow>=10.2.0.20240213; extra == 'dev'
+Requires-Dist: types-tqdm>=4.66.0.20240106; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# About
+
+Videopython is a minimal video generation and processing library designed with short-form videos in mind, with focus on simplicity and ease of use for both humans and AI agents.
+
+# Setup
+
+## Install ffmpeg
+```bash
+# Install with brew for MacOS:
+brew install ffmpeg
+# Install with apt-get for Ubuntu:
+sudo apt-get install ffmpeg
+```
+
+## Install library
+
+```bash
+# Install with your favourite package manager
+uv add videopython --extra ai
+
+# pip install works as well :)
+pip install videopython[ai]
+```
+
+> You can install without `[ai]` dependencies for basic video handling and processing.
+> The functionalities found in `videopython.ai` won't work.
+
+# Usage examples
+
+## Basic video editing
+
+```python
+from videopython.base.video import Video
+
+# Load videos and print metadata
+video1 = Video.from_path("tests/test_data/small_video.mp4")
+print(video1)
+
+video2 = Video.from_path("tests/test_data/big_video.mp4")
+print(video2)
+
+# Define the transformations
+from videopython.base.transforms import CutSeconds, ResampleFPS, Resize, TransformationPipeline
+
+pipeline = TransformationPipeline(
+    [CutSeconds(start=1.5, end=6.5), ResampleFPS(fps=30), Resize(width=1000, height=1000)]
+)
+video1 = pipeline.run(video1)
+video2 = pipeline.run(video2)
+
+# Combine videos, add audio and save
+from videopython.base.transitions import FadeTransition
+
+fade = FadeTransition(effect_time_seconds=3.0)
+video = fade.apply(videos=(video1, video2))
+video.add_audio_from_file("tests/test_data/test_audio.mp3")
+
+savepath = video.save()
+```
+
+## AI powered examples
+
+### Video Generation
+
+> Using Nvidia A40 or better is recommended for the `videopython.ai` module.
+```python
+# Generate image and animate it
+from videopython.ai.generation import ImageToVideo
+from videopython.ai.generation import TextToImage
+
+image = TextToImage().generate_image(prompt="Golden Retriever playing in the park")
+video = ImageToVideo().generate_video(image=image, fps=24)
+
+# Video generation directly from prompt
+from videopython.ai.generation import TextToVideo
+video_gen = TextToVideo()
+video = video_gen.generate_video("Dogs playing in the park")
+for _ in range(10):
+    video += video_gen.generate_video("Dogs playing in the park")
+```
+
+### Audio generation
+```python
+from videopython.base.video import Video
+video = Video.from_path("<PATH_TO_VIDEO>")
+
+# Generate music on top of video
+from videopython.ai.generation import TextToMusic
+text_to_music = TextToMusic()
+audio = text_to_music.generate_audio("Happy dogs playing together in a park", max_new_tokens=256)
+video.add_audio(audio=audio)
+
+# Add TTS on top of video
+from videopython.ai.generation import TextToSpeech
+text_to_speech = TextToSpeech()
+audio = text_to_speech.generate_audio("Woof woof woof! Woooooof!")
+video.add_audio(audio=audio)
+```
+
+### Generate and overlay subtitles
+```python
+from videopython.base.video import Video
+video = Video.from_path("<PATH_TO_VIDEO>")
+
+# Generate transcription with timestamps
+from videopython.ai.understanding.transcribe import CreateTranscription
+transcription = CreateTranscription("base").transcribe(video)
+# Initialise object for overlaying. See `TranscriptionOverlay` to see detailed configuration options.
+from videopython.base.text.overlay import TranscriptionOverlay
+transcription_overlay = TranscriptionOverlay(font_filename="src/tests/test_data/test_font.ttf")
+
+video = transcription_overlay.apply(video, transcription)
+video.save()
+```
+
+# Development notes
+
+## Project structure
+
+Source code of the project can be found under `src/` directory, along with separate directories for unit tests and mypy stubs.
+```
+.
+└── src
+    ├── stubs # Contains stubs for mypy
+    ├── tests # Unit tests
+    └── videopython # Library code
+```
+
+----
+
+The `videopython` library is divided into 2 separate high-level modules:
+* `videopython.base`: Contains base classes for handling videos and for basic video editing. There are no imports from `videopython.ai` within the `base` module, which allows users to install light-weight base dependencies to do simple video operations.
+* `videopython.ai`: Contains AI-powered functionalities for video generation. It has its own `ai` dependency group, which contains all dependencies required to run AI models.
+
+## Running locally
+
+We are using [uv](https://docs.astral.sh/uv/) as project and package manager. Once you clone the repo and install uv locally, you can use it to sync the dependencies.
+```bash
+uv sync --all-extras
+```
+
+To run the unit tests, you can simply run:
+```bash
+uv run pytest
+```
+
+We also use [Ruff](https://docs.astral.sh/ruff/) for linting/formatting and [mypy](https://github.com/python/mypy) as type checker.
+```bash
+# Run formatting
+uv run ruff format
+# Run linting and apply fixes
+uv run ruff check --fix
+# Run type checks
+uv run mypy src/
+```

videopython-0.5.0/README.md

@@ -0,0 +1,155 @@
+# About
+
+Videopython is a minimal video generation and processing library designed with short-form videos in mind, with focus on simplicity and ease of use for both humans and AI agents.
+
+# Setup
+
+## Install ffmpeg
+```bash
+# Install with brew for MacOS:
+brew install ffmpeg
+# Install with apt-get for Ubuntu:
+sudo apt-get install ffmpeg
+```
+
+## Install library
+
+```bash
+# Install with your favourite package manager
+uv add videopython --extra ai
+
+# pip install works as well :)
+pip install videopython[ai]
+```
+
+> You can install without `[ai]` dependencies for basic video handling and processing.
+> The functionalities found in `videopython.ai` won't work.
+
+# Usage examples
+
+## Basic video editing
+
+```python
+from videopython.base.video import Video
+
+# Load videos and print metadata
+video1 = Video.from_path("tests/test_data/small_video.mp4")
+print(video1)
+
+video2 = Video.from_path("tests/test_data/big_video.mp4")
+print(video2)
+
+# Define the transformations
+from videopython.base.transforms import CutSeconds, ResampleFPS, Resize, TransformationPipeline
+
+pipeline = TransformationPipeline(
+    [CutSeconds(start=1.5, end=6.5), ResampleFPS(fps=30), Resize(width=1000, height=1000)]
+)
+video1 = pipeline.run(video1)
+video2 = pipeline.run(video2)
+
+# Combine videos, add audio and save
+from videopython.base.transitions import FadeTransition
+
+fade = FadeTransition(effect_time_seconds=3.0)
+video = fade.apply(videos=(video1, video2))
+video.add_audio_from_file("tests/test_data/test_audio.mp3")
+
+savepath = video.save()
+```
+
+## AI powered examples
+
+### Video Generation
+
+> Using Nvidia A40 or better is recommended for the `videopython.ai` module.
+```python
+# Generate image and animate it
+from videopython.ai.generation import ImageToVideo
+from videopython.ai.generation import TextToImage
+
+image = TextToImage().generate_image(prompt="Golden Retriever playing in the park")
+video = ImageToVideo().generate_video(image=image, fps=24)
+
+# Video generation directly from prompt
+from videopython.ai.generation import TextToVideo
+video_gen = TextToVideo()
+video = video_gen.generate_video("Dogs playing in the park")
+for _ in range(10):
+    video += video_gen.generate_video("Dogs playing in the park")
+```
+
+### Audio generation
+```python
+from videopython.base.video import Video
+video = Video.from_path("<PATH_TO_VIDEO>")
+
+# Generate music on top of video
+from videopython.ai.generation import TextToMusic
+text_to_music = TextToMusic()
+audio = text_to_music.generate_audio("Happy dogs playing together in a park", max_new_tokens=256)
+video.add_audio(audio=audio)
+
+# Add TTS on top of video
+from videopython.ai.generation import TextToSpeech
+text_to_speech = TextToSpeech()
+audio = text_to_speech.generate_audio("Woof woof woof! Woooooof!")
+video.add_audio(audio=audio)
+```
+
+### Generate and overlay subtitles
+```python
+from videopython.base.video import Video
+video = Video.from_path("<PATH_TO_VIDEO>")
+
+# Generate transcription with timestamps
+from videopython.ai.understanding.transcribe import CreateTranscription
+transcription = CreateTranscription("base").transcribe(video)
+# Initialise object for overlaying. See `TranscriptionOverlay` to see detailed configuration options.
+from videopython.base.text.overlay import TranscriptionOverlay
+transcription_overlay = TranscriptionOverlay(font_filename="src/tests/test_data/test_font.ttf")
+
+video = transcription_overlay.apply(video, transcription)
+video.save()
+```
+
+# Development notes
+
+## Project structure
+
+Source code of the project can be found under `src/` directory, along with separate directories for unit tests and mypy stubs.
+```
+.
+└── src
+    ├── stubs # Contains stubs for mypy
+    ├── tests # Unit tests
+    └── videopython # Library code
+```
+
+----
+
+The `videopython` library is divided into 2 separate high-level modules:
+* `videopython.base`: Contains base classes for handling videos and for basic video editing. There are no imports from `videopython.ai` within the `base` module, which allows users to install light-weight base dependencies to do simple video operations.
+* `videopython.ai`: Contains AI-powered functionalities for video generation. It has its own `ai` dependency group, which contains all dependencies required to run AI models.
+
+## Running locally
+
+We are using [uv](https://docs.astral.sh/uv/) as project and package manager. Once you clone the repo and install uv locally, you can use it to sync the dependencies.
+```bash
+uv sync --all-extras
+```
+
+To run the unit tests, you can simply run:
+```bash
+uv run pytest
+```
+
+We also use [Ruff](https://docs.astral.sh/ruff/) for linting/formatting and [mypy](https://github.com/python/mypy) as type checker.
+```bash
+# Run formatting
+uv run ruff format
+# Run linting and apply fixes
+uv run ruff check --fix
+# Run type checks
+uv run mypy src/
+```

{videopython-0.4.0 → videopython-0.5.0}/pyproject.toml

@@ -1,21 +1,32 @@
 [project]
 name = "videopython"
-version = "0.4.0"
+version = "0.5.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
     { name = "Bartosz Rudnikowicz", email = "bartoszrudnikowicz840@gmail.com" },
-    { name = "Piotr Pukisz", email = "piotr.pukisz@gmail.com" }
+    { name = "Piotr Pukisz", email = "piotr.pukisz@gmail.com" },
 ]
 license = { text = "Apache-2.0" }
 readme = "README.md"
 requires-python = ">=3.10, <3.13"
-keywords = ["python", "videopython", "video", "movie", "opencv", "generation", "editing"]
+keywords = [
+    "python",
+    "videopython",
+    "video",
+    "movie",
+    "opencv",
+    "generation",
+    "editing",
+    "ai",
+    "shorts",
+]
 classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Operating System :: OS Independent",
 ]
 
@@ -23,10 +34,8 @@ dependencies = [
     "numpy>=1.25.2",
     "opencv-python>=4.9.0.80",
     "pillow>=10.3.0",
-    "pydub>=0.25.1",
-    "soundpython>=0.1.11",
     "tqdm>=4.66.3",
-    
+    "soundpython>=0.1.11",
 ]
 
 [dependency-groups]
@@ -47,6 +56,25 @@ ai = [
     "numba>=0.61.0",
 ]
 
+# We have to keep it to make PIP use those dependency groups, not only UV
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.1.14",
+    "mypy>=1.8.0",
+    "pytest>=7.4.0",
+    "types-Pillow>=10.2.0.20240213",
+    "types-tqdm>=4.66.0.20240106",
+    "pytest-cov>=6.1.1",
+]
+ai = [
+    "accelerate>=0.29.2",
+    "diffusers>=0.26.3",
+    "torch>=2.1.0",
+    "transformers>=4.38.1",
+    "openai-whisper>=20240930",
+    "numba>=0.61.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/bartwojtowicz/videopython/"
 Repository = "https://github.com/bartwojtowicz/videopython/"
@@ -77,9 +105,9 @@ target-version = "py310"
 
 [tool.ruff.lint]
 select = [
-    "E",   # pycodestyle errors
-    "F",   # pyflakes
-    "I",   # isort
+    "E", # pycodestyle errors
+    "F", # pyflakes
+    "I", # isort
 ]
 isort.known-first-party = ["videopython"]
 

videopython-0.5.0/src/videopython/ai/understanding/transcribe.py

@@ -0,0 +1,66 @@
+from typing import Literal, Union
+
+import whisper
+from soundpython import Audio
+
+from videopython.base.text.transcription import Transcription, TranscriptionSegment, TranscriptionWord
+from videopython.base.video import Video
+
+
+class CreateTranscription:
+    """Unified transcription service for both audio and video."""
+
+    def __init__(self, model_name: Literal["tiny", "base", "small", "medium", "large", "turbo"] = "small") -> None:
+        self.model = whisper.load_model(name=model_name)
+
+    def _process_transcription_result(self, transcription_result: dict) -> Transcription:
+        """Process raw transcription result into Transcription object.
+
+        Args:
+            transcription_result: Raw result from whisper model
+
+        Returns:
+            Processed Transcription object
+        """
+        transcription_segments = []
+        for segment in transcription_result["segments"]:
+            transcription_words = [
+                TranscriptionWord(word=word["word"], start=float(word["start"]), end=float(word["end"]))
+                for word in segment["words"]
+            ]
+            transcription_segment = TranscriptionSegment(
+                start=segment["start"], end=segment["end"], text=segment["text"], words=transcription_words
+            )
+            transcription_segments.append(transcription_segment)
+
+        return Transcription(segments=transcription_segments)
+
+    def transcribe(self, media: Union[Audio, Video]) -> Transcription:
+        """Transcribe audio or video to text.
+
+        Args:
+            media: Audio or Video to transcribe.
+
+        Returns:
+            Transcription object with segments of text and their timestamps.
+        """
+        if isinstance(media, Video):
+            # Handle video transcription
+            if media.audio.is_silent:
+                return Transcription(segments=[])
+
+            audio = media.audio.to_mono().resample(whisper.audio.SAMPLE_RATE)
+            transcription_result = self.model.transcribe(audio=audio.data, word_timestamps=True)
+
+        elif isinstance(media, Audio):
+            # Handle audio transcription
+            if media.is_silent:
+                return Transcription(segments=[])
+
+            audio = media.to_mono().resample(whisper.audio.SAMPLE_RATE)
+            transcription_result = self.model.transcribe(audio=audio.data, word_timestamps=True)
+
+        else:
+            raise TypeError(f"Unsupported media type: {type(media)}. Expected Audio or Video.")
+
+        return self._process_transcription_result(transcription_result)

videopython-0.5.0/src/videopython/base/combine.py

@@ -0,0 +1,45 @@
+from typing import Literal
+
+import numpy as np
+
+from videopython.base.transforms import ResampleFPS, Resize
+from videopython.base.video import Video
+
+
+class StackVideos:
+    def __init__(self, mode: Literal["horizontal", "vertical"]) -> None:
+        self.mode = mode
+
+    def _validate(self, video1: Video, video2: Video) -> tuple[Video, Video]:
+        video1, video2 = self._align_shapes(video1, video2)
+        video1, video2 = self._align_fps(video1, video2)
+        video1, video2 = self._align_duration(video1, video2)
+        return video1, video2
+
+    def _align_fps(self, video1: Video, video2: Video) -> tuple[Video, Video]:
+        if video1.fps > video2.fps:
+            video1 = ResampleFPS(fps=video2.fps).apply(video1)
+        elif video1.fps < video2.fps:
+            video2 = ResampleFPS(fps=video1.fps).apply(video2)
+        return (video1, video2)
+
+    def _align_shapes(self, video1: Video, video2: Video) -> tuple[Video, Video]:
+        if self.mode == "horizontal":
+            video2 = Resize(height=video1.metadata.height).apply(video2)
+        elif self.mode == "vertical":
+            video2 = Resize(width=video1.metadata.width).apply(video2)
+        return (video1, video2)
+
+    def _align_duration(self, video1: Video, video2: Video) -> tuple[Video, Video]:
+        if len(video1.frames) > len(video2.frames):
+            video1 = video1[: len(video2.frames)]
+        elif len(video1.frames) < len(video2.frames):
+            video2 = video2[: len(video1.frames)]
+        return (video1, video2)
+
+    def apply(self, videos: tuple[Video, Video]) -> Video:
+        videos = self._validate(*videos)
+        axis = 1 if self.mode == "vertical" else 2
+        new_frames = np.concatenate((videos[0].frames, videos[1].frames), axis=axis)
+        new_audio = videos[0].audio.overlay(videos[1].audio)
+        return Video(frames=new_frames, fps=videos[0].fps, audio=new_audio)