# MP4SVG - Video to SVG Converter
A Python package that converts MP4 video files into SVG containers using various encoding methods, with full roundtrip extraction capabilities.
## Features
- **Multiple Encoding Methods**: ASCII85, Polyglot, Vector Animation, QR Code, and Hybrid
- **XML-Safe Embedding**: Proper handling of binary data in SVG/XML context
- **Interactive SVG**: Embedded JavaScript for in-browser video playback
- **Thumbnail Previews**: JPEG thumbnails for system/browser compatibility
- **Data Integrity**: Built-in validation and checksum verification
- **CLI Interface**: Command-line tools for conversion and extraction
- **Extensible Architecture**: Modular design for easy extension
## Installation
### From Source
```bash
git clone <repository-url>
cd mp4svg
pip install -e .
```
### Dependencies
- Python 3.8+
- OpenCV (cv2)
- NumPy
- Pillow (PIL)
- qrcode
- lxml
## Quick Start
### Command Line Usage
```bash
# Convert MP4 to SVG using ASCII85 encoding
mp4svg input.mp4 output.svg --method ascii85
# Extract MP4 from SVG
mp4svg output.svg extracted.mp4 --extract
# Use polyglot method with custom chunk size
mp4svg input.mp4 output.svg --method polyglot --chunk-size 4096
# Convert to QR codes with error correction
mp4svg input.mp4 output.svg --method qrcode --error-correction M
# Try all methods and compare (hybrid)
mp4svg input.mp4 output.svg --method hybrid
```
### Python API
```python
from mp4svg import ASCII85SVGConverter, PolyglotSVGConverter
# ASCII85 encoding (recommended for most use cases)
converter = ASCII85SVGConverter()
svg_path = converter.convert('video.mp4', 'output.svg')
# Extract back to MP4
success = converter.extract('output.svg', 'extracted.mp4')
# Polyglot embedding (larger files, better compatibility)
polyglot = PolyglotSVGConverter()
svg_path = polyglot.convert('video.mp4', 'polyglot.svg')
```
## Encoding Methods
### 1. ASCII85 (Recommended)
- **Best for**: General use, good compression ratio
- **Overhead**: ~25% size increase
- **Features**: Interactive playback, thumbnail preview, XML-safe
- **Roundtrip**: Full fidelity extraction
```python
from mp4svg import ASCII85SVGConverter
converter = ASCII85SVGConverter()
```
### 2. Polyglot
- **Best for**: Maximum compatibility, embedded metadata
- **Overhead**: ~33% size increase
- **Features**: SVG + embedded binary data, summary statistics
- **Roundtrip**: Full fidelity extraction
```python
from mp4svg import PolyglotSVGConverter
converter = PolyglotSVGConverter()
```
### 3. Vector Animation
- **Best for**: Stylized animation, artistic effects
- **Overhead**: Variable (depends on complexity)
- **Features**: True vector animation, scalable
- **Roundtrip**: Not supported (lossy conversion)
```python
from mp4svg import SVGVectorFrameConverter
converter = SVGVectorFrameConverter()
```
### 4. QR Code
- **Best for**: Educational purposes, distributed storage
- **Overhead**: Very high (~10x size increase)
- **Features**: Multiple QR frames, chunk-based storage
- **Roundtrip**: Full fidelity with extraction script
```python
from mp4svg import QRCodeSVGConverter
converter = QRCodeSVGConverter(chunk_size=1000)
```
### 5. Hybrid
- **Best for**: Comparing all methods, choosing optimal
- **Features**: Tests all methods, size comparison, format detection
- **Output**: Multiple files with performance report
```python
from mp4svg import HybridSVGConverter
converter = HybridSVGConverter()
```
## SVG Validation
The package includes comprehensive validation utilities:
```python
from mp4svg.validators import SVGValidator, IntegrityValidator
# Validate SVG structure and detect format
svg_validator = SVGValidator()
result = svg_validator.validate_svg_file('output.svg')
# Check data integrity and extraction
integrity_validator = IntegrityValidator()
integrity_result = integrity_validator.validate_integrity('output.svg', 'original.mp4')
# Batch validate directory
batch_result = integrity_validator.batch_validate('/path/to/svg/files/')
```
## Interactive SVG Features
Generated SVG files include:
- **Thumbnail Preview**: JPEG thumbnail for system compatibility
- **Play Button**: Click to decode and play video
- **JavaScript Decoder**: Built-in ASCII85/Base64 decoder
- **Error Handling**: Robust namespace and element selection
## Project Structure
```
mp4svg/
├── src/mp4svg/
│ ├── __init__.py # Package exports
│ ├── base.py # Base converter class
│ ├── ascii85.py # ASCII85 converter
│ ├── polyglot.py # Polyglot converter
│ ├── vector.py # Vector animation converter
│ ├── qrcode.py # QR code converter
│ ├── hybrid.py # Hybrid converter
│ ├── cli.py # Command-line interface
│ └── validators/ # Validation utilities
│ ├── __init__.py
│ ├── svg_validator.py
│ └── integrity_validator.py
├── tests/ # Test suite
├── pyproject.toml # Poetry configuration
└── README.md # This file
```
## Testing
Run the test suite:
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_converters.py -v
# Run with coverage
pytest --cov=src/mp4svg tests/
```
## Advanced Usage
### Custom Conversion Settings
```python
# ASCII85 with custom settings
converter = ASCII85SVGConverter()
converter.thumbnail_quality = 85
converter.max_size_mb = 50
# Polyglot with custom boundary
polyglot = PolyglotSVGConverter()
polyglot.chunk_size = 8192
# Vector with animation settings
vector = SVGVectorFrameConverter()
vector.frame_duration = 0.1
vector.edge_threshold = 100
# QR with error correction
qr = QRCodeSVGConverter(
chunk_size=500,
error_correction='H', # High error correction
border=2
)
```
### Batch Processing
```python
import os
from mp4svg import ASCII85SVGConverter
converter = ASCII85SVGConverter()
# Convert all MP4 files in directory
input_dir = '/path/to/videos/'
output_dir = '/path/to/svg_output/'
for filename in os.listdir(input_dir):
if filename.endswith('.mp4'):
input_path = os.path.join(input_dir, filename)
output_path = os.path.join(output_dir, filename.replace('.mp4', '.svg'))
try:
converter.convert(input_path, output_path)
print(f"Converted: {filename}")
except Exception as e:
print(f"Failed to convert {filename}: {e}")
```
### Validation Pipeline
```python
from mp4svg.validators import SVGValidator, IntegrityValidator
# Complete validation pipeline
def validate_conversion(original_mp4, generated_svg):
# Structure validation
svg_validator = SVGValidator()
svg_result = svg_validator.validate_svg_file(generated_svg)
if not svg_result['is_well_formed']:
print("SVG is not well-formed XML")
return False
# Integrity validation
integrity_validator = IntegrityValidator()
integrity_result = integrity_validator.validate_integrity(
generated_svg, original_mp4
)
if not integrity_result['data_integrity_valid']:
print("Data integrity check failed")
return False
print(f"Validation successful: {svg_result['detected_format']} format")
return True
```
## Troubleshooting
### Common Issues
1. **XML Parsing Errors**
- Ensure input MP4 is not corrupted
- Check file size limits (default: 100MB)
- Validate with `SVGValidator`
2. **JavaScript Not Working in Browser**
- Check browser console for errors
- Ensure SVG is served with correct MIME type
- Modern browser required for ES6 features
3. **Extraction Failures**
- Verify SVG format detection
- Check embedded data integrity
- Use validation utilities
4. **Large File Performance**
- Use chunked processing for very large videos
- Consider polyglot method for better memory usage
- Set appropriate `max_size_mb` limits
### Debug Mode
```python
import logging
logging.basicConfig(level=logging.DEBUG)
from mp4svg import ASCII85SVGConverter
converter = ASCII85SVGConverter()
# Detailed logging will be displayed
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
Apache 2.0 License - see LICENSE file for details.
## Changelog
### v1.0.0
- Initial release with ASCII85, Polyglot, Vector, QR Code converters
- Interactive SVG with JavaScript playback
- Comprehensive validation utilities
- CLI interface
- Full test coverage
Raw data
{
"_id": null,
"home_page": "https://github.com/veridock/mp4svg",
"name": "mp4svg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": null,
"keywords": "video, svg, conversion, ascii85, polyglot",
"author": "Tom Sapletta",
"author_email": "info@softreck.dev",
"download_url": "https://files.pythonhosted.org/packages/c6/fe/62362439c9ed40962751b3f871b4389b9991e40b164e7c10e6223356d1ea/mp4svg-1.0.10.tar.gz",
"platform": null,
"description": "# MP4SVG - Video to SVG Converter\n\nA Python package that converts MP4 video files into SVG containers using various encoding methods, with full roundtrip extraction capabilities.\n\n## Features\n\n- **Multiple Encoding Methods**: ASCII85, Polyglot, Vector Animation, QR Code, and Hybrid\n- **XML-Safe Embedding**: Proper handling of binary data in SVG/XML context\n- **Interactive SVG**: Embedded JavaScript for in-browser video playback\n- **Thumbnail Previews**: JPEG thumbnails for system/browser compatibility\n- **Data Integrity**: Built-in validation and checksum verification\n- **CLI Interface**: Command-line tools for conversion and extraction\n- **Extensible Architecture**: Modular design for easy extension\n\n## Installation\n\n### From Source\n```bash\ngit clone <repository-url>\ncd mp4svg\npip install -e .\n```\n\n### Dependencies\n- Python 3.8+\n- OpenCV (cv2)\n- NumPy\n- Pillow (PIL)\n- qrcode\n- lxml\n\n## Quick Start\n\n### Command Line Usage\n\n```bash\n# Convert MP4 to SVG using ASCII85 encoding\nmp4svg input.mp4 output.svg --method ascii85\n\n# Extract MP4 from SVG\nmp4svg output.svg extracted.mp4 --extract\n\n# Use polyglot method with custom chunk size\nmp4svg input.mp4 output.svg --method polyglot --chunk-size 4096\n\n# Convert to QR codes with error correction\nmp4svg input.mp4 output.svg --method qrcode --error-correction M\n\n# Try all methods and compare (hybrid)\nmp4svg input.mp4 output.svg --method hybrid\n```\n\n### Python API\n\n```python\nfrom mp4svg import ASCII85SVGConverter, PolyglotSVGConverter\n\n# ASCII85 encoding (recommended for most use cases)\nconverter = ASCII85SVGConverter()\nsvg_path = converter.convert('video.mp4', 'output.svg')\n\n# Extract back to MP4\nsuccess = converter.extract('output.svg', 'extracted.mp4')\n\n# Polyglot embedding (larger files, better compatibility)\npolyglot = PolyglotSVGConverter()\nsvg_path = polyglot.convert('video.mp4', 'polyglot.svg')\n```\n\n## Encoding Methods\n\n### 1. ASCII85 (Recommended)\n- **Best for**: General use, good compression ratio\n- **Overhead**: ~25% size increase\n- **Features**: Interactive playback, thumbnail preview, XML-safe\n- **Roundtrip**: Full fidelity extraction\n\n```python\nfrom mp4svg import ASCII85SVGConverter\nconverter = ASCII85SVGConverter()\n```\n\n### 2. Polyglot\n- **Best for**: Maximum compatibility, embedded metadata\n- **Overhead**: ~33% size increase \n- **Features**: SVG + embedded binary data, summary statistics\n- **Roundtrip**: Full fidelity extraction\n\n```python\nfrom mp4svg import PolyglotSVGConverter\nconverter = PolyglotSVGConverter()\n```\n\n### 3. Vector Animation\n- **Best for**: Stylized animation, artistic effects\n- **Overhead**: Variable (depends on complexity)\n- **Features**: True vector animation, scalable\n- **Roundtrip**: Not supported (lossy conversion)\n\n```python\nfrom mp4svg import SVGVectorFrameConverter\nconverter = SVGVectorFrameConverter()\n```\n\n### 4. QR Code\n- **Best for**: Educational purposes, distributed storage\n- **Overhead**: Very high (~10x size increase)\n- **Features**: Multiple QR frames, chunk-based storage\n- **Roundtrip**: Full fidelity with extraction script\n\n```python\nfrom mp4svg import QRCodeSVGConverter\nconverter = QRCodeSVGConverter(chunk_size=1000)\n```\n\n### 5. Hybrid\n- **Best for**: Comparing all methods, choosing optimal\n- **Features**: Tests all methods, size comparison, format detection\n- **Output**: Multiple files with performance report\n\n```python\nfrom mp4svg import HybridSVGConverter\nconverter = HybridSVGConverter()\n```\n\n## SVG Validation\n\nThe package includes comprehensive validation utilities:\n\n```python\nfrom mp4svg.validators import SVGValidator, IntegrityValidator\n\n# Validate SVG structure and detect format\nsvg_validator = SVGValidator()\nresult = svg_validator.validate_svg_file('output.svg')\n\n# Check data integrity and extraction\nintegrity_validator = IntegrityValidator()\nintegrity_result = integrity_validator.validate_integrity('output.svg', 'original.mp4')\n\n# Batch validate directory\nbatch_result = integrity_validator.batch_validate('/path/to/svg/files/')\n```\n\n## Interactive SVG Features\n\nGenerated SVG files include:\n- **Thumbnail Preview**: JPEG thumbnail for system compatibility\n- **Play Button**: Click to decode and play video\n- **JavaScript Decoder**: Built-in ASCII85/Base64 decoder\n- **Error Handling**: Robust namespace and element selection\n\n## Project Structure\n\n```\nmp4svg/\n\u251c\u2500\u2500 src/mp4svg/\n\u2502 \u251c\u2500\u2500 __init__.py # Package exports\n\u2502 \u251c\u2500\u2500 base.py # Base converter class\n\u2502 \u251c\u2500\u2500 ascii85.py # ASCII85 converter\n\u2502 \u251c\u2500\u2500 polyglot.py # Polyglot converter \n\u2502 \u251c\u2500\u2500 vector.py # Vector animation converter\n\u2502 \u251c\u2500\u2500 qrcode.py # QR code converter\n\u2502 \u251c\u2500\u2500 hybrid.py # Hybrid converter\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 validators/ # Validation utilities\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 svg_validator.py\n\u2502 \u2514\u2500\u2500 integrity_validator.py\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 pyproject.toml # Poetry configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest tests/\n\n# Run specific test file\npytest tests/test_converters.py -v\n\n# Run with coverage\npytest --cov=src/mp4svg tests/\n```\n\n## Advanced Usage\n\n### Custom Conversion Settings\n\n```python\n# ASCII85 with custom settings\nconverter = ASCII85SVGConverter()\nconverter.thumbnail_quality = 85\nconverter.max_size_mb = 50\n\n# Polyglot with custom boundary\npolyglot = PolyglotSVGConverter()\npolyglot.chunk_size = 8192\n\n# Vector with animation settings \nvector = SVGVectorFrameConverter()\nvector.frame_duration = 0.1\nvector.edge_threshold = 100\n\n# QR with error correction\nqr = QRCodeSVGConverter(\n chunk_size=500,\n error_correction='H', # High error correction\n border=2\n)\n```\n\n### Batch Processing\n\n```python\nimport os\nfrom mp4svg import ASCII85SVGConverter\n\nconverter = ASCII85SVGConverter()\n\n# Convert all MP4 files in directory\ninput_dir = '/path/to/videos/'\noutput_dir = '/path/to/svg_output/'\n\nfor filename in os.listdir(input_dir):\n if filename.endswith('.mp4'):\n input_path = os.path.join(input_dir, filename)\n output_path = os.path.join(output_dir, filename.replace('.mp4', '.svg'))\n \n try:\n converter.convert(input_path, output_path)\n print(f\"Converted: {filename}\")\n except Exception as e:\n print(f\"Failed to convert {filename}: {e}\")\n```\n\n### Validation Pipeline\n\n```python\nfrom mp4svg.validators import SVGValidator, IntegrityValidator\n\n# Complete validation pipeline\ndef validate_conversion(original_mp4, generated_svg):\n # Structure validation\n svg_validator = SVGValidator()\n svg_result = svg_validator.validate_svg_file(generated_svg)\n \n if not svg_result['is_well_formed']:\n print(\"SVG is not well-formed XML\")\n return False\n \n # Integrity validation \n integrity_validator = IntegrityValidator()\n integrity_result = integrity_validator.validate_integrity(\n generated_svg, original_mp4\n )\n \n if not integrity_result['data_integrity_valid']:\n print(\"Data integrity check failed\")\n return False\n \n print(f\"Validation successful: {svg_result['detected_format']} format\")\n return True\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **XML Parsing Errors**\n - Ensure input MP4 is not corrupted\n - Check file size limits (default: 100MB)\n - Validate with `SVGValidator`\n\n2. **JavaScript Not Working in Browser**\n - Check browser console for errors\n - Ensure SVG is served with correct MIME type\n - Modern browser required for ES6 features\n\n3. **Extraction Failures**\n - Verify SVG format detection\n - Check embedded data integrity\n - Use validation utilities\n\n4. **Large File Performance**\n - Use chunked processing for very large videos\n - Consider polyglot method for better memory usage\n - Set appropriate `max_size_mb` limits\n\n### Debug Mode\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\nfrom mp4svg import ASCII85SVGConverter\nconverter = ASCII85SVGConverter()\n# Detailed logging will be displayed\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nApache 2.0 License - see LICENSE file for details.\n\n## Changelog\n\n### v1.0.0\n- Initial release with ASCII85, Polyglot, Vector, QR Code converters\n- Interactive SVG with JavaScript playback\n- Comprehensive validation utilities\n- CLI interface\n- Full test coverage",
"bugtrack_url": null,
"license": null,
"summary": "Convert MP4 videos to SVG containers using multiple encoding methods",
"version": "1.0.10",
"project_urls": {
"Documentation": "https://mp4svg.readthedocs.io",
"Homepage": "https://github.com/veridock/mp4svg",
"Repository": "https://github.com/veridock/mp4svg"
},
"split_keywords": [
"video",
" svg",
" conversion",
" ascii85",
" polyglot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c74588f379d14d22fbb01fa3633f6ded87c897304c89099aae4c7a99549bc8e4",
"md5": "f8a7eac245fc3837736d33ca4bd08b80",
"sha256": "a9e5b9aa156cf6ad2599d2d014bb37dabf0eb23d282e875b2825e2f7c5fdfc74"
},
"downloads": -1,
"filename": "mp4svg-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f8a7eac245fc3837736d33ca4bd08b80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 64059,
"upload_time": "2025-08-08T13:33:20",
"upload_time_iso_8601": "2025-08-08T13:33:20.150677Z",
"url": "https://files.pythonhosted.org/packages/c7/45/88f379d14d22fbb01fa3633f6ded87c897304c89099aae4c7a99549bc8e4/mp4svg-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6fe62362439c9ed40962751b3f871b4389b9991e40b164e7c10e6223356d1ea",
"md5": "f74514738c65bce653c3ba556bfa45c5",
"sha256": "967eedc23ce3b3faa93b680253fafc4c00f27bff3341b2a61a5d9e572d1a4952"
},
"downloads": -1,
"filename": "mp4svg-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "f74514738c65bce653c3ba556bfa45c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 55626,
"upload_time": "2025-08-08T13:33:21",
"upload_time_iso_8601": "2025-08-08T13:33:21.443989Z",
"url": "https://files.pythonhosted.org/packages/c6/fe/62362439c9ed40962751b3f871b4389b9991e40b164e7c10e6223356d1ea/mp4svg-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 13:33:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "veridock",
"github_project": "mp4svg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "opencv-python",
"specs": [
[
">=",
"4.8.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "qrcode",
"specs": [
[
">=",
"7.4.0"
]
]
},
{
"name": "lxml",
"specs": [
[
">=",
"4.9.0"
]
]
}
],
"lcname": "mp4svg"
}
JSON
