# 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/
```
Raw data
{
"_id": null,
"home_page": null,
"name": "videopython",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "ai, editing, generation, movie, opencv, python, shorts, video, videopython",
"author": null,
"author_email": "Bartosz W\u00f3jtowicz <bartoszwojtowicz@outlook.com>, Bartosz Rudnikowicz <bartoszrudnikowicz840@gmail.com>, Piotr Pukisz <piotr.pukisz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/68/5b/cff5fcada5fa13bfd857c292443fd0015619b009e654df78f936dde9088f/videopython-0.5.0.tar.gz",
"platform": null,
"description": "# About\n\nVideopython 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.\n\n# Setup\n\n## Install ffmpeg\n```bash\n# Install with brew for MacOS:\nbrew install ffmpeg\n# Install with apt-get for Ubuntu:\nsudo apt-get install ffmpeg\n```\n\n## Install library\n\n```bash\n# Install with your favourite package manager\nuv add videopython --extra ai\n\n# pip install works as well :)\npip install videopython[ai]\n```\n\n> You can install without `[ai]` dependencies for basic video handling and processing.\n> The functionalities found in `videopython.ai` won't work.\n\n# Usage examples\n\n## Basic video editing\n\n```python\nfrom videopython.base.video import Video\n\n# Load videos and print metadata\nvideo1 = Video.from_path(\"tests/test_data/small_video.mp4\")\nprint(video1)\n\nvideo2 = Video.from_path(\"tests/test_data/big_video.mp4\")\nprint(video2)\n\n# Define the transformations\nfrom videopython.base.transforms import CutSeconds, ResampleFPS, Resize, TransformationPipeline\n\npipeline = TransformationPipeline(\n [CutSeconds(start=1.5, end=6.5), ResampleFPS(fps=30), Resize(width=1000, height=1000)]\n)\nvideo1 = pipeline.run(video1)\nvideo2 = pipeline.run(video2)\n\n# Combine videos, add audio and save\nfrom videopython.base.transitions import FadeTransition\n\nfade = FadeTransition(effect_time_seconds=3.0)\nvideo = fade.apply(videos=(video1, video2))\nvideo.add_audio_from_file(\"tests/test_data/test_audio.mp3\")\n\nsavepath = video.save()\n```\n\n## AI powered examples\n\n### Video Generation\n\n> Using Nvidia A40 or better is recommended for the `videopython.ai` module.\n```python\n# Generate image and animate it\nfrom videopython.ai.generation import ImageToVideo\nfrom videopython.ai.generation import TextToImage\n\nimage = TextToImage().generate_image(prompt=\"Golden Retriever playing in the park\")\nvideo = ImageToVideo().generate_video(image=image, fps=24)\n\n# Video generation directly from prompt\nfrom videopython.ai.generation import TextToVideo\nvideo_gen = TextToVideo()\nvideo = video_gen.generate_video(\"Dogs playing in the park\")\nfor _ in range(10):\n video += video_gen.generate_video(\"Dogs playing in the park\")\n```\n\n### Audio generation\n```python\nfrom videopython.base.video import Video\nvideo = Video.from_path(\"<PATH_TO_VIDEO>\")\n\n# Generate music on top of video\nfrom videopython.ai.generation import TextToMusic\ntext_to_music = TextToMusic()\naudio = text_to_music.generate_audio(\"Happy dogs playing together in a park\", max_new_tokens=256)\nvideo.add_audio(audio=audio)\n\n# Add TTS on top of video\nfrom videopython.ai.generation import TextToSpeech\ntext_to_speech = TextToSpeech()\naudio = text_to_speech.generate_audio(\"Woof woof woof! Woooooof!\")\nvideo.add_audio(audio=audio)\n```\n\n### Generate and overlay subtitles\n```python\nfrom videopython.base.video import Video\nvideo = Video.from_path(\"<PATH_TO_VIDEO>\")\n\n# Generate transcription with timestamps\nfrom videopython.ai.understanding.transcribe import CreateTranscription\ntranscription = CreateTranscription(\"base\").transcribe(video)\n# Initialise object for overlaying. See `TranscriptionOverlay` to see detailed configuration options.\nfrom videopython.base.text.overlay import TranscriptionOverlay\ntranscription_overlay = TranscriptionOverlay(font_filename=\"src/tests/test_data/test_font.ttf\")\n\nvideo = transcription_overlay.apply(video, transcription)\nvideo.save()\n```\n\n# Development notes\n\n## Project structure\n\nSource code of the project can be found under `src/` directory, along with separate directories for unit tests and mypy stubs.\n```\n.\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 stubs # Contains stubs for mypy\n \u251c\u2500\u2500 tests # Unit tests\n \u2514\u2500\u2500 videopython # Library code\n```\n\n----\n\nThe `videopython` library is divided into 2 separate high-level modules:\n* `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.\n* `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.\n\n## Running locally\n\nWe 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.\n```bash\nuv sync --all-extras\n```\n\nTo run the unit tests, you can simply run:\n```bash\nuv run pytest\n```\n\nWe also use [Ruff](https://docs.astral.sh/ruff/) for linting/formatting and [mypy](https://github.com/python/mypy) as type checker.\n```bash\n# Run formatting\nuv run ruff format\n# Run linting and apply fixes\nuv run ruff check --fix\n# Run type checks\nuv run mypy src/\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Minimal video generation and processing library.",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://github.com/bartwojtowicz/videopython/",
"Homepage": "https://github.com/bartwojtowicz/videopython/",
"Repository": "https://github.com/bartwojtowicz/videopython/"
},
"split_keywords": [
"ai",
" editing",
" generation",
" movie",
" opencv",
" python",
" shorts",
" video",
" videopython"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ebf9cb66b0f0b129c41827023a174fd21044e0f6ac84ed98550dae04176d9236",
"md5": "ff8347d9731ee252d407d0221fc1e0dc",
"sha256": "4b2341f133c5b906d84838d9232304a283e949d844e5fd9a691db19a31227edb"
},
"downloads": -1,
"filename": "videopython-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff8347d9731ee252d407d0221fc1e0dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 34085,
"upload_time": "2025-07-08T19:50:54",
"upload_time_iso_8601": "2025-07-08T19:50:54.340734Z",
"url": "https://files.pythonhosted.org/packages/eb/f9/cb66b0f0b129c41827023a174fd21044e0f6ac84ed98550dae04176d9236/videopython-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "685bcff5fcada5fa13bfd857c292443fd0015619b009e654df78f936dde9088f",
"md5": "c8124ba930403e6d4a38c86651ff4883",
"sha256": "c5c4cd793d8287466634843f4b38255fedc4695d47bd8de5e1931b4c5e17dbb4"
},
"downloads": -1,
"filename": "videopython-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "c8124ba930403e6d4a38c86651ff4883",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 29158,
"upload_time": "2025-07-08T19:50:56",
"upload_time_iso_8601": "2025-07-08T19:50:56.107377Z",
"url": "https://files.pythonhosted.org/packages/68/5b/cff5fcada5fa13bfd857c292443fd0015619b009e654df78f936dde9088f/videopython-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 19:50:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bartwojtowicz",
"github_project": "videopython",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "videopython"
}
JSON
