# MetaToolkit
[](https://badge.fury.io/py/metatoolkit)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A powerful Python library for processing metadata of images, videos, and audio files. Supports adding, reading, and managing metadata information for various media files.
## Features
- 🖼️ **Image Metadata Processing** - Support for EXIF, XMP metadata in JPEG, PNG formats
- 🎬 **Video Metadata Processing** - Support for metadata tags in MP4, AVI and other formats
- 🎵 **Audio Metadata Processing** - Support for ID3 tags in MP3, WAV and other formats
- 📝 **Custom Metadata** - Support for adding custom metadata fields
- 🔧 **Command Line Tool** - Convenient command-line interface
- 🐍 **Python API** - Simple and easy-to-use Python interface
## Installation
### Install from PyPI
```bash
pip install metatoolkit
```
### Install from Source
```bash
git clone https://github.com/ihmily/metatoolkit.git
cd metatoolkit
pip install -e .
```
### Requirements
- Python >= 3.10
- Pillow >= 9.5.0
- pyexiv2 >= 2.15.4
> **Note**: Video and audio metadata writing functionality requires FFmpeg environment. Please ensure FFmpeg is properly installed on your system and accessible from the command line.
## Quick Start
### Image Metadata Processing
```python
import metatoolkit
from datetime import datetime
# Add custom metadata to image
custom_metadata = {
"model": "stable-diffusion-v1.5",
"prompt": "A beautiful landscape",
"timestamp": datetime.now().isoformat(),
"creator": "MetaToolkit"
}
# Add metadata
output_path = metatoolkit.add_image_metadata("input.png", custom_metadata=custom_metadata)
# Read metadata
metadata = metatoolkit.read_image_metadata(output_path)
print(metadata)
```
### Video Metadata Processing
```python
import metatoolkit
# Add video metadata
video_metadata = {
"title": "My Video",
"description": "This is a test video",
"author": "MetaToolkit User",
"creation_date": "2024-01-01"
}
# Add metadata
metatoolkit.add_video_metadata("input.mp4", custom_metadata=video_metadata)
# Read metadata
metadata = metatoolkit.read_video_metadata("input.mp4")
print(metadata)
```
### Audio Metadata Processing
```python
import metatoolkit
# Add audio metadata
audio_metadata = {
"title": "My Music",
"artist": "Artist Name",
"album": "Album Name",
"year": "2024"
}
# Add metadata
metatoolkit.add_audio_metadata("input.mp3", custom_metadata=audio_metadata)
# Read metadata
metadata = metatoolkit.read_audio_metadata("input.mp3")
print(metadata)
```
## Command Line Tool
MetaToolkit provides a convenient command-line tool that can be used directly in the terminal:
```bash
# Show help
metatoolkit --help
# Add image metadata
metatoolkit image add image.png --field MyTag='{\"title\":\"My Image\",\"author\":\"User\"}'
# Read image metadata
metatoolkit image read image.png
# Add video metadata
metatoolkit video add video.mp4 --field MyTag1=MyTest01 --field MyTag2=MyTest02
# Read video metadata
metatoolkit video read video.mp4
# Add audio metadata
metatoolkit audio add audio.mp3 --field MyTag1=MyTest01 --field MyTag2=MyTest02 --field MyTag3=MyTest03
# Read audio metadata
metatoolkit audio read audio.mp3
```
## API Reference
### Image Processing
- `add_image_metadata(image_path, custom_metadata=None, output_path=None)` - Add image metadata
- `read_image_metadata(image_path)` - Read image metadata
- `get_all_image_metadata(image_path)` - Get all image metadata
### Video Processing
- `add_video_metadata(video_path, custom_metadata=metadata_dict)` - Add video metadata
- `read_video_metadata(video_path)` - Read video metadata
- `get_all_video_metadata(video_path)` - Get all video metadata
### Audio Processing
- `add_audio_metadata(audio_path, custom_metadata=metadata_dict)` - Add audio metadata
- `read_audio_metadata(audio_path)` - Read audio metadata
- `get_all_audio_metadata(audio_path)` - Get all audio metadata
## Supported Formats
### Image Formats
- JPEG (.jpg, .jpeg)
- PNG (.png)
### Video Formats
- MP4 (.mp4)
- AVI (.avi)
- MOV (.mov)
- MKV (.mkv)
### Audio Formats
- MP3 (.mp3)
- WAV (.wav)
- FLAC (.flac)
- M4A (.m4a)
- OGG (.ogg)
- AAC (.aac)
## Related Tools
### Viewing and Verifying Metadata
#### ExifTool
[ExifTool](https://exiftool.org/) is a powerful command-line tool for reading, writing, and editing metadata in various file formats. It's particularly useful for viewing and verifying metadata in images.
```bash
# View all metadata in an image
exiftool image.png
# View metadata in a video
exiftool video.mp4
# View metadata in a audio
exiftool audio.mp3
```
#### FFprobe
FFprobe is part of the FFmpeg suite and is excellent for analyzing audio and video files.
```bash
# View video metadata
ffprobe -v quiet -print_format json -show_format -show_streams video.mp4
# View audio metadata
ffprobe -v quiet -print_format json -show_format audio.mp3
```
### Installation
```bash
# Install ExifTool (Windows)
# Download from https://exiftool.org/
# Install ExifTool (macOS)
brew install exiftool
# Install ExifTool (Ubuntu/Debian)
sudo apt-get install libimage-exiftool-perl
# Install FFmpeg/FFprobe (Windows)
# Download from https://ffmpeg.org/download.html
# Install FFmpeg/FFprobe (macOS)
brew install ffmpeg
# Install FFmpeg/FFprobe (Ubuntu/Debian)
sudo apt-get install ffmpeg
```
## Examples
Check the `examples/basic_usage.py` file for more usage examples.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version update history.
## Contact
- Project Homepage: https://github.com/ihmily/metatoolkit
- Issue Tracker: https://github.com/ihmily/metatoolkit/issues
## Acknowledgments
Thanks to all the developers who contributed to this project!
Raw data
{
"_id": null,
"home_page": "https://github.com/ihmily/metatoolkit",
"name": "metatoolkit",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "image, metadata, exif, watermark, video, audio",
"author": "Hmily",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/34/b7/f4ac143ccb39d0115b684a4c8f9018b496b7a9c8ce4ab87ba2b31e4710f2/metatoolkit-0.1.1.tar.gz",
"platform": null,
"description": "# MetaToolkit\n\n[](https://badge.fury.io/py/metatoolkit)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA powerful Python library for processing metadata of images, videos, and audio files. Supports adding, reading, and managing metadata information for various media files.\n\n## Features\n\n- \ud83d\uddbc\ufe0f **Image Metadata Processing** - Support for EXIF, XMP metadata in JPEG, PNG formats\n- \ud83c\udfac **Video Metadata Processing** - Support for metadata tags in MP4, AVI and other formats\n- \ud83c\udfb5 **Audio Metadata Processing** - Support for ID3 tags in MP3, WAV and other formats\n- \ud83d\udcdd **Custom Metadata** - Support for adding custom metadata fields\n- \ud83d\udd27 **Command Line Tool** - Convenient command-line interface\n- \ud83d\udc0d **Python API** - Simple and easy-to-use Python interface\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install metatoolkit\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/ihmily/metatoolkit.git\ncd metatoolkit\npip install -e .\n```\n\n### Requirements\n\n- Python >= 3.10\n- Pillow >= 9.5.0\n- pyexiv2 >= 2.15.4\n\n> **Note**: Video and audio metadata writing functionality requires FFmpeg environment. Please ensure FFmpeg is properly installed on your system and accessible from the command line.\n\n## Quick Start\n\n### Image Metadata Processing\n\n```python\nimport metatoolkit\nfrom datetime import datetime\n\n# Add custom metadata to image\ncustom_metadata = {\n \"model\": \"stable-diffusion-v1.5\",\n \"prompt\": \"A beautiful landscape\",\n \"timestamp\": datetime.now().isoformat(),\n \"creator\": \"MetaToolkit\"\n}\n\n# Add metadata\noutput_path = metatoolkit.add_image_metadata(\"input.png\", custom_metadata=custom_metadata)\n\n# Read metadata\nmetadata = metatoolkit.read_image_metadata(output_path)\nprint(metadata)\n```\n\n### Video Metadata Processing\n\n```python\nimport metatoolkit\n\n# Add video metadata\nvideo_metadata = {\n \"title\": \"My Video\",\n \"description\": \"This is a test video\",\n \"author\": \"MetaToolkit User\",\n \"creation_date\": \"2024-01-01\"\n}\n\n# Add metadata\nmetatoolkit.add_video_metadata(\"input.mp4\", custom_metadata=video_metadata)\n\n# Read metadata\nmetadata = metatoolkit.read_video_metadata(\"input.mp4\")\nprint(metadata)\n```\n\n### Audio Metadata Processing\n\n```python\nimport metatoolkit\n\n# Add audio metadata\naudio_metadata = {\n \"title\": \"My Music\",\n \"artist\": \"Artist Name\",\n \"album\": \"Album Name\",\n \"year\": \"2024\"\n}\n\n# Add metadata\nmetatoolkit.add_audio_metadata(\"input.mp3\", custom_metadata=audio_metadata)\n\n# Read metadata\nmetadata = metatoolkit.read_audio_metadata(\"input.mp3\")\nprint(metadata)\n```\n\n## Command Line Tool\n\nMetaToolkit provides a convenient command-line tool that can be used directly in the terminal:\n\n```bash\n# Show help\nmetatoolkit --help\n\n# Add image metadata\nmetatoolkit image add image.png --field MyTag='{\\\"title\\\":\\\"My Image\\\",\\\"author\\\":\\\"User\\\"}'\n\n# Read image metadata\nmetatoolkit image read image.png\n\n# Add video metadata\nmetatoolkit video add video.mp4 --field MyTag1=MyTest01 --field MyTag2=MyTest02\n\n# Read video metadata\nmetatoolkit video read video.mp4\n\n# Add audio metadata\nmetatoolkit audio add audio.mp3 --field MyTag1=MyTest01 --field MyTag2=MyTest02 --field MyTag3=MyTest03\n\n# Read audio metadata\nmetatoolkit audio read audio.mp3\n```\n\n## API Reference\n\n### Image Processing\n\n- `add_image_metadata(image_path, custom_metadata=None, output_path=None)` - Add image metadata\n- `read_image_metadata(image_path)` - Read image metadata\n- `get_all_image_metadata(image_path)` - Get all image metadata\n\n### Video Processing\n\n- `add_video_metadata(video_path, custom_metadata=metadata_dict)` - Add video metadata\n- `read_video_metadata(video_path)` - Read video metadata\n- `get_all_video_metadata(video_path)` - Get all video metadata\n\n### Audio Processing\n\n- `add_audio_metadata(audio_path, custom_metadata=metadata_dict)` - Add audio metadata\n- `read_audio_metadata(audio_path)` - Read audio metadata\n- `get_all_audio_metadata(audio_path)` - Get all audio metadata\n\n## Supported Formats\n\n### Image Formats\n\n- JPEG (.jpg, .jpeg)\n- PNG (.png)\n\n### Video Formats\n\n- MP4 (.mp4)\n- AVI (.avi)\n- MOV (.mov)\n- MKV (.mkv)\n\n### Audio Formats\n\n- MP3 (.mp3)\n- WAV (.wav)\n- FLAC (.flac)\n- M4A (.m4a)\n- OGG (.ogg)\n- AAC (.aac)\n\n## Related Tools\n\n### Viewing and Verifying Metadata\n\n#### ExifTool\n\n[ExifTool](https://exiftool.org/) is a powerful command-line tool for reading, writing, and editing metadata in various file formats. It's particularly useful for viewing and verifying metadata in images.\n\n```bash\n# View all metadata in an image\nexiftool image.png\n\n# View metadata in a video\nexiftool video.mp4\n\n# View metadata in a audio\nexiftool audio.mp3\n```\n\n#### FFprobe\n\nFFprobe is part of the FFmpeg suite and is excellent for analyzing audio and video files.\n\n```bash\n# View video metadata\nffprobe -v quiet -print_format json -show_format -show_streams video.mp4\n\n# View audio metadata\nffprobe -v quiet -print_format json -show_format audio.mp3\n```\n\n### Installation\n\n```bash\n# Install ExifTool (Windows)\n# Download from https://exiftool.org/\n\n# Install ExifTool (macOS)\nbrew install exiftool\n\n# Install ExifTool (Ubuntu/Debian)\nsudo apt-get install libimage-exiftool-perl\n\n# Install FFmpeg/FFprobe (Windows)\n# Download from https://ffmpeg.org/download.html\n\n# Install FFmpeg/FFprobe (macOS)\nbrew install ffmpeg\n\n# Install FFmpeg/FFprobe (Ubuntu/Debian)\nsudo apt-get install ffmpeg\n```\n\n## Examples\n\nCheck the `examples/basic_usage.py` file for more usage examples.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version update history.\n\n## Contact\n\n- Project Homepage: https://github.com/ihmily/metatoolkit\n- Issue Tracker: https://github.com/ihmily/metatoolkit/issues\n\n## Acknowledgments\n\nThanks to all the developers who contributed to this project!",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful Python library for processing metadata of images, videos, and audio files",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://metatoolkit.readthedocs.io",
"Homepage": "https://github.com/ihmily/metatoolkit",
"Source": "https://github.com/ihmily/metatoolkit"
},
"split_keywords": [
"image",
" metadata",
" exif",
" watermark",
" video",
" audio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d63f04c09f1c15c165156b64d5520adb4d3130c8d87067eb1a93b3981b1d9087",
"md5": "6e9cba3c5711b7004b0a5e227b7690f6",
"sha256": "b1cb9a333706ea0a28349c91f9d3c24a7268e3d03f55880d9a0965e9891ee323"
},
"downloads": -1,
"filename": "metatoolkit-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e9cba3c5711b7004b0a5e227b7690f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 15613,
"upload_time": "2025-09-08T04:19:26",
"upload_time_iso_8601": "2025-09-08T04:19:26.282115Z",
"url": "https://files.pythonhosted.org/packages/d6/3f/04c09f1c15c165156b64d5520adb4d3130c8d87067eb1a93b3981b1d9087/metatoolkit-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34b7f4ac143ccb39d0115b684a4c8f9018b496b7a9c8ce4ab87ba2b31e4710f2",
"md5": "390421eecebfb94a11114837f2bd0e77",
"sha256": "24d04b2fb579c66ea30a7a4f541f82603495b4bd7d5233810b499f4c76d317e5"
},
"downloads": -1,
"filename": "metatoolkit-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "390421eecebfb94a11114837f2bd0e77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 12035,
"upload_time": "2025-09-08T04:19:27",
"upload_time_iso_8601": "2025-09-08T04:19:27.459383Z",
"url": "https://files.pythonhosted.org/packages/34/b7/f4ac143ccb39d0115b684a4c8f9018b496b7a9c8ce4ab87ba2b31e4710f2/metatoolkit-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 04:19:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ihmily",
"github_project": "metatoolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Pillow",
"specs": [
[
">=",
"9.5.0"
]
]
},
{
"name": "pyexiv2",
"specs": [
[
">=",
"2.15.4"
]
]
}
],
"lcname": "metatoolkit"
}
JSON
