videopython 0.4.1__tar.gz → 0.5.0__tar.gz

{videopython-0.4.1 → videopython-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.4.1
+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/
@@ -8,12 +8,13 @@ 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: editing,generation,movie,opencv,python,video,videopython
+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
@@ -38,11 +39,11 @@ Description-Content-Type: text/markdown
 
 # About
 
-Minimal video generation and processing library.
+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 
+# Setup
 
-### Install ffmpeg
+## Install ffmpeg
 ```bash
 # Install with brew for MacOS:
 brew install ffmpeg
@@ -50,16 +51,22 @@ brew install ffmpeg
 sudo apt-get install ffmpeg
 ```
 
-### Install with pip
+## 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 funcionalities found in `videopython.ai` won't work.
 
-## Basic Usage
+> You can install without `[ai]` dependencies for basic video handling and processing.
+> The functionalities found in `videopython.ai` won't work.
+
+# Usage examples
 
-### Video handling
+## Basic video editing
 
 ```python
 from videopython.base.video import Video
@@ -90,6 +97,8 @@ 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.
@@ -97,7 +106,6 @@ savepath = video.save()
 # Generate image and animate it
 from videopython.ai.generation import ImageToVideo
 from videopython.ai.generation import TextToImage
-from videopython.ai.generation import TextToMusic
 
 image = TextToImage().generate_image(prompt="Golden Retriever playing in the park")
 video = ImageToVideo().generate_video(image=image, fps=24)
@@ -105,27 +113,82 @@ 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 snow")
+video = video_gen.generate_video("Dogs playing in the park")
 for _ in range(10):
-    video += video_gen.generate_video("Dogs playing in the snow")
-
-# Cut the first 2 seconds
-from videopython.base.transforms import CutSeconds
-transformed_video = CutSeconds(start_second=0, end_second=2).apply(video.copy())
-
-# Upsample to 30 FPS
-from videopython.base.transforms import ResampleFPS
-transformed_video = ResampleFPS(new_fps=30).apply(transformed_video)
+    video += video_gen.generate_video("Dogs playing in the park")
+```
 
-# Resize to 1000x1000
-from videopython.base.transforms import Resize
-transformed_video = Resize(width=1000, height=1000).apply(transformed_video)
+### Audio generation
+```python
+from videopython.base.video import Video
+video = Video.from_path("<PATH_TO_VIDEO>")
 
-# Add generated music
-# MusicGen cannot generate more than 1503 tokens (~30seconds of audio)
+# 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)
-transformed_video.add_audio(audio=audio)
+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")
 
-filepath = transformed_video.save()
+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.1 → videopython-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.4.1"
+version = "0.5.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -18,12 +18,15 @@ keywords = [
     "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",
 ]
 

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)