videopython


Namevideopython JSON
Version 0.5.0 PyPI version JSON
download
home_pageNone
SummaryMinimal video generation and processing library.
upload_time2025-07-08 19:50:56
maintainerNone
docs_urlNone
authorNone
requires_python<3.13,>=3.10
licenseApache-2.0
keywords ai editing generation movie opencv python shorts video videopython
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.41377s