# VidKit
A simple and powerful Python package for generating videos from JSON configurations. VidKit makes it easy to create videos by combining images, setting durations, and adding audio tracks.
## Installation
```bash
pip install vidkit
```
## Quick Start
```python
from vidkit import renderVideo, saveVideo
# Define your video configuration
config = {
"name": "my_video",
"format": "mp4",
"framerate": 30, # Note: 'framerate' instead of 'fps'
"resolution": [1920, 1080], # Note: array instead of object
"frames": [
{
"image": "frame1.jpg",
"duration": 5
},
{
"image": "frame2.jpg",
"duration": 5
}
],
"audio": "background.mp3"
}
# Generate and save the video
video_bytes = renderVideo(config)
saveVideo(video_bytes, "output.mp4")
```
## Features
- Simple JSON-based configuration
- Support for multiple image frames
- Audio track integration
- Fast video generation using moviepy
- Flexible resolution settings
- Configurable frame rates
- Metadata preservation
- Error handling and validation
## Configuration Options
The video configuration accepts the following parameters:
| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|-----------|---------|
| name | string | Name of the video | Yes | - |
| format | string | Output format (currently 'mp4') | Yes | - |
| framerate | number | Frame rate in FPS | Yes | - |
| resolution | [width, height] | Video dimensions in pixels | Yes | - |
| frames | array | List of frame objects | Yes | - |
| audio | string | Path to audio file | No | None |
### Frame Object Properties
| Property | Type | Description | Required | Default |
|----------|------|-------------|-----------|---------|
| image | string | Path to image file | Yes | - |
| duration | number | Duration in seconds | Yes | - |
## Advanced Usage
### 1. Error Handling
```python
from vidkit import renderVideo, saveVideo
try:
video_bytes = renderVideo(config)
saveVideo(video_bytes, "output.mp4")
except ValueError as e:
print(f"Configuration error: {e}")
except FileNotFoundError as e:
print(f"File not found: {e}")
except Exception as e:
print(f"An error occurred: {e}")
```
### 2. Retrieving Video Configuration
VidKit automatically stores the configuration in the video's metadata. You can retrieve it using:
```python
from vidkit import get_config
try:
config = get_config("output.mp4")
print("Video configuration:", config)
except KeyError:
print("No VidKit configuration found in metadata")
except ValueError as e:
print(f"Error reading configuration: {e}")
```
### 3. Configuration as JSON File
You can also store your configuration in a JSON file:
```python
import json
from vidkit import renderVideo
# Load configuration from file
with open("video_config.json", "r") as f:
config = json.load(f)
# Generate video
video_bytes = renderVideo(config)
```
Example `video_config.json`:
```json
{
"name": "my_video",
"format": "mp4",
"framerate": 30,
"resolution": [1920, 1080],
"frames": [
{
"image": "frame1.jpg",
"duration": 5
},
{
"image": "frame2.jpg",
"duration": 5
}
],
"audio": "background.mp3"
}
```
## Common Issues and Solutions
1. **Image Not Found**
- Ensure all image paths in the configuration are correct and accessible
- Use absolute paths or paths relative to your script's location
2. **Audio Sync Issues**
- Make sure the total duration of frames matches your audio duration
- Use the same framerate throughout your project
3. **Memory Issues**
- When working with high-resolution images, consider reducing their size
- Process videos in smaller segments if needed
## Requirements
- Python >= 3.6
- moviepy >= 2.0.0
- Pillow >= 9.2.0
- numpy >= 1.25.0
- mutagen >= 1.45.0 (for metadata handling)
## Contributing
Contributions are welcome! Here's how you can help:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run the tests (`python test.py`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
### Development Setup
```bash
# Clone the repository
git clone https://github.com/SpyC0der77/vidkit.git
cd vidkit
# Install development dependencies
pip install -e ".[dev]"
# Run tests
python test.py
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
Created by Carter Stach ([@SpyC0der77](https://github.com/SpyC0der77))
## Support
- **Issues**: If you encounter any issues or have questions, please [open an issue](https://github.com/SpyC0der77/vidkit/issues) on GitHub
- **Discussions**: For general questions and discussions, use the [GitHub Discussions](https://github.com/SpyC0der77/vidkit/discussions) page
- **Security**: For security-related issues, please email carter.stach@gmail.com
## Changelog
### 0.1.2
- Fixed metadata handling in MP4 files
- Improved error messages
- Updated documentation
### 0.1.1
- Initial release
- Basic video generation functionality
- Audio support
- Metadata storage
Raw data
{
"_id": null,
"home_page": "https://github.com/SpyC0der77/vidkit",
"name": "vidkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "video generation, json, moviepy, video editing",
"author": "Carter Stach",
"author_email": "carter.stach@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/72/7b/6454c85ce8940c30e47ce3c4fb7a84064d93d926131cb9795d8b32f7a782/vidkit-0.1.3.2.tar.gz",
"platform": null,
"description": "# VidKit \r\n\r\nA simple and powerful Python package for generating videos from JSON configurations. VidKit makes it easy to create videos by combining images, setting durations, and adding audio tracks.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install vidkit\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom vidkit import renderVideo, saveVideo\r\n\r\n# Define your video configuration\r\nconfig = {\r\n \"name\": \"my_video\",\r\n \"format\": \"mp4\",\r\n \"framerate\": 30, # Note: 'framerate' instead of 'fps'\r\n \"resolution\": [1920, 1080], # Note: array instead of object\r\n \"frames\": [\r\n {\r\n \"image\": \"frame1.jpg\",\r\n \"duration\": 5\r\n },\r\n {\r\n \"image\": \"frame2.jpg\",\r\n \"duration\": 5\r\n }\r\n ],\r\n \"audio\": \"background.mp3\"\r\n}\r\n\r\n# Generate and save the video\r\nvideo_bytes = renderVideo(config)\r\nsaveVideo(video_bytes, \"output.mp4\")\r\n```\r\n\r\n## Features\r\n\r\n- Simple JSON-based configuration\r\n- Support for multiple image frames\r\n- Audio track integration\r\n- Fast video generation using moviepy\r\n- Flexible resolution settings\r\n- Configurable frame rates\r\n- Metadata preservation\r\n- Error handling and validation\r\n\r\n## Configuration Options\r\n\r\nThe video configuration accepts the following parameters:\r\n\r\n| Parameter | Type | Description | Required | Default |\r\n|-----------|------|-------------|-----------|---------|\r\n| name | string | Name of the video | Yes | - |\r\n| format | string | Output format (currently 'mp4') | Yes | - |\r\n| framerate | number | Frame rate in FPS | Yes | - |\r\n| resolution | [width, height] | Video dimensions in pixels | Yes | - |\r\n| frames | array | List of frame objects | Yes | - |\r\n| audio | string | Path to audio file | No | None |\r\n\r\n### Frame Object Properties\r\n\r\n| Property | Type | Description | Required | Default |\r\n|----------|------|-------------|-----------|---------|\r\n| image | string | Path to image file | Yes | - |\r\n| duration | number | Duration in seconds | Yes | - |\r\n\r\n## Advanced Usage\r\n\r\n### 1. Error Handling\r\n\r\n```python\r\nfrom vidkit import renderVideo, saveVideo\r\n\r\ntry:\r\n video_bytes = renderVideo(config)\r\n saveVideo(video_bytes, \"output.mp4\")\r\nexcept ValueError as e:\r\n print(f\"Configuration error: {e}\")\r\nexcept FileNotFoundError as e:\r\n print(f\"File not found: {e}\")\r\nexcept Exception as e:\r\n print(f\"An error occurred: {e}\")\r\n```\r\n\r\n### 2. Retrieving Video Configuration\r\n\r\nVidKit automatically stores the configuration in the video's metadata. You can retrieve it using:\r\n\r\n```python\r\nfrom vidkit import get_config\r\n\r\ntry:\r\n config = get_config(\"output.mp4\")\r\n print(\"Video configuration:\", config)\r\nexcept KeyError:\r\n print(\"No VidKit configuration found in metadata\")\r\nexcept ValueError as e:\r\n print(f\"Error reading configuration: {e}\")\r\n```\r\n\r\n### 3. Configuration as JSON File\r\n\r\nYou can also store your configuration in a JSON file:\r\n\r\n```python\r\nimport json\r\nfrom vidkit import renderVideo\r\n\r\n# Load configuration from file\r\nwith open(\"video_config.json\", \"r\") as f:\r\n config = json.load(f)\r\n\r\n# Generate video\r\nvideo_bytes = renderVideo(config)\r\n```\r\n\r\nExample `video_config.json`:\r\n```json\r\n{\r\n \"name\": \"my_video\",\r\n \"format\": \"mp4\",\r\n \"framerate\": 30,\r\n \"resolution\": [1920, 1080],\r\n \"frames\": [\r\n {\r\n \"image\": \"frame1.jpg\",\r\n \"duration\": 5\r\n },\r\n {\r\n \"image\": \"frame2.jpg\",\r\n \"duration\": 5\r\n }\r\n ],\r\n \"audio\": \"background.mp3\"\r\n}\r\n```\r\n\r\n## Common Issues and Solutions\r\n\r\n1. **Image Not Found**\r\n - Ensure all image paths in the configuration are correct and accessible\r\n - Use absolute paths or paths relative to your script's location\r\n\r\n2. **Audio Sync Issues**\r\n - Make sure the total duration of frames matches your audio duration\r\n - Use the same framerate throughout your project\r\n\r\n3. **Memory Issues**\r\n - When working with high-resolution images, consider reducing their size\r\n - Process videos in smaller segments if needed\r\n\r\n## Requirements\r\n\r\n- Python >= 3.6\r\n- moviepy >= 2.0.0\r\n- Pillow >= 9.2.0\r\n- numpy >= 1.25.0\r\n- mutagen >= 1.45.0 (for metadata handling)\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Here's how you can help:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes\r\n4. Run the tests (`python test.py`)\r\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n6. Push to the branch (`git push origin feature/amazing-feature`)\r\n7. Open a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/SpyC0der77/vidkit.git\r\ncd vidkit\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npython test.py\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Author\r\n\r\nCreated by Carter Stach ([@SpyC0der77](https://github.com/SpyC0der77))\r\n\r\n## Support\r\n\r\n- **Issues**: If you encounter any issues or have questions, please [open an issue](https://github.com/SpyC0der77/vidkit/issues) on GitHub\r\n- **Discussions**: For general questions and discussions, use the [GitHub Discussions](https://github.com/SpyC0der77/vidkit/discussions) page\r\n- **Security**: For security-related issues, please email carter.stach@gmail.com\r\n\r\n## Changelog\r\n\r\n### 0.1.2\r\n- Fixed metadata handling in MP4 files\r\n- Improved error messages\r\n- Updated documentation\r\n\r\n### 0.1.1\r\n- Initial release\r\n- Basic video generation functionality\r\n- Audio support\r\n- Metadata storage\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for generating videos from JSON specifications",
"version": "0.1.3.2",
"project_urls": {
"Homepage": "https://github.com/SpyC0der77/vidkit"
},
"split_keywords": [
"video generation",
" json",
" moviepy",
" video editing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b85ea6bd88e1b88d7765949d2e5320e397fd026b9e1e458da560f3c65716f28",
"md5": "d8618cdeb78d3973458bda91ec84a499",
"sha256": "bffcf2f4cd71602cebe18cadc54e8569ff98482e1627a29622f931341724cdd0"
},
"downloads": -1,
"filename": "vidkit-0.1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8618cdeb78d3973458bda91ec84a499",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6586,
"upload_time": "2024-11-24T17:23:12",
"upload_time_iso_8601": "2024-11-24T17:23:12.588761Z",
"url": "https://files.pythonhosted.org/packages/3b/85/ea6bd88e1b88d7765949d2e5320e397fd026b9e1e458da560f3c65716f28/vidkit-0.1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "727b6454c85ce8940c30e47ce3c4fb7a84064d93d926131cb9795d8b32f7a782",
"md5": "5396d9291ac013eaf78e9f0290adbe56",
"sha256": "cc8e6607a5d6be918d9a1f121fe8e00be82446485ad65ad0e271f13318158077"
},
"downloads": -1,
"filename": "vidkit-0.1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "5396d9291ac013eaf78e9f0290adbe56",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7602,
"upload_time": "2024-11-24T17:23:13",
"upload_time_iso_8601": "2024-11-24T17:23:13.657312Z",
"url": "https://files.pythonhosted.org/packages/72/7b/6454c85ce8940c30e47ce3c4fb7a84064d93d926131cb9795d8b32f7a782/vidkit-0.1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 17:23:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpyC0der77",
"github_project": "vidkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "moviepy",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.2.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.25.0"
]
]
},
{
"name": "mutagen",
"specs": [
[
">=",
"1.45.0"
]
]
}
],
"lcname": "vidkit"
}
JSON
