{"id":23277649,"url":"https://github.com/socaity/media-toolkit","last_synced_at":"2025-10-27T16:30:46.781Z","repository":{"id":245183248,"uuid":"815205467","full_name":"SocAIty/media-toolkit","owner":"SocAIty","description":"Web-ready standardized file processing and serialization. Read, write, convert and send files. Including image, audio, video and any other file. Easily convert between numpy, base64, bytes and more.","archived":false,"fork":false,"pushed_at":"2025-02-06T21:48:20.000Z","size":4091,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T22:31:23.284Z","etag":null,"topics":["base64","bytesio","fast-task-api","httpx","image-processing","json","numpy","serialization","video"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SocAIty.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"SocAIty","patreon":"w4hns1nn","buy_me_a_coffee":"socaity","custom":["paypal.me/SocaityRieger"]}},"created_at":"2024-06-14T15:24:54.000Z","updated_at":"2025-02-06T21:48:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5114684-f089-42ee-8dcc-2d12d0587503","html_url":"https://github.com/SocAIty/media-toolkit","commit_stats":null,"previous_names":["socaity/multimodal-files"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocAIty%2Fmedia-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocAIty%2Fmedia-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocAIty%2Fmedia-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocAIty%2Fmedia-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SocAIty","download_url":"https://codeload.github.com/SocAIty/media-toolkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238523994,"owners_count":19486600,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["base64","bytesio","fast-task-api","httpx","image-processing","json","numpy","serialization","video"],"created_at":"2024-12-19T22:13:38.596Z","updated_at":"2025-10-27T16:30:41.212Z","avatar_url":"https://github.com/SocAIty.png","language":"Python","funding_links":["https://github.com/sponsors/SocAIty","https://patreon.com/w4hns1nn","https://buymeacoffee.com/socaity","paypal.me/SocaityRieger"],"categories":[],"sub_categories":[],"readme":"\n  \u003ch1 align=\"center\" style=\"margin-top:-25px\"\u003eMediaToolkit\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg align=\"center\" src=\"docs/media-file-icon.png\" height=\"200\" /\u003e\n\u003c/p\u003e\n  \u003ch3 align=\"center\" style=\"margin-top:-10px\"\u003eWeb-ready standardized file processing and serialization\u003c/h3\u003e\n\n\n# Features\n\nRead, load and convert to standard file types with a common interface.\nEspecially useful for code that works with multiple file types like images, audio, video, etc.\n\nLoad and convert from and to common data types:\n- numpy arrays \n- file paths \n- bytes,\n- base64\n- json\n- urls\n- etc.\n\nTransmit files between services with a common interface\n- Native [FastSDK](https://github.com/SocAIty/fastSDK) and [FastTaskAPI](https://github.com/SocAIty/FastTaskAPI) integration\n- Supports httpx, requests\n\nWork with native python libs like BytesIO.\n\nOnly use the file types you need, no unnecessary dependencies.\n\n## Installation\n\nYou can install the package with PIP, or clone the repository. \n\n```bash\n# install from pypi\npip install media-toolkit\n# install without dependencies: this is useful if you only need the basic functionality (working with files)\npip install media-toolkit --no-deps\n# if you want to use certain file types, and convenience functions\npip install media-toolkit[VideoFile]  # or [AudioFile, VideoFile, ...]\n# install from github for newest release\npip install git+git://github.com/SocAIty/media-toolkit\n```\nThe package checks if you have missing dependencies for certain file types while using. \nUse the ```--no-deps``` flag for a minimal tiny pure python installation.\nThe package with dependencies is quite small \u003c 39kb itself.\n\nNote: for VideoFile you will also need to install [ffmpeg](https://ffmpeg.org/download.html)\n\n# Usage\n\n## Create a media-file from any data type\nThe library automatically detects the data type and loads it correctly.\n\n```python\nfrom media_toolkit import MediaFile, ImageFile, AudioFile, VideoFile\n\n# could be a path, url, base64, bytesio, file_handle, numpy array ...\narbitrary_data = \"....\"\n# Instantiate an image file\nnew_file = ImageFile().from_any(arbitrary_data)\n```\n\nAll files ```(ImageFile, AudioFile, VideoFile)``` types support the same interface / methods.\n\n#### Explicitly load from a certain type.\nThis method is more secure than from_any, because it definitely uses the correct method to load the file.\n```python\nnew_file = MediaFile()\n\nnew_file.from_file(\"path/to/file\")\nnew_file.from_file(open(\"path/to/file\", \"rb\"))\nnew_file.from_numpy_array(my_array)\nnew_file.from_bytes(b'bytes')\nnew_file.from_base64('base64string')\nnew_file.from_starlette_upload_file(starlette_upload_file)\n\n```\n\n## Convert to any format or write to file\nSupports common serialization methods like bytes(), np.array(), dict()\n\n```python\nmy_file = ImageFile().from_file(\"path/to/my_image.png\")\n\nmy_file.save(\"path/to/new_file.png\")  \nas_numpy_array = my_file.to_numpy_array()\nas_numpy_array = np.array(my_file)\n\nas_bytes = my_file.to_bytes()\nas_bytes = bytes(my_file)\nas_base64 = my_file.to_base64()\nas_json = my_file.to_json()\n```\n\n### Working with VideoFiles.\n\nThe VideoFiles wrap the famous [vidgear](https://abhitronix.github.io/vidgear/latest/) package as well as [pydub](https://github.com/jiaaro/pydub).\nVideoFiles support extra methods like audio extraction, combining video and audio.\nVidgear is a powerful video processing library that supports many video formats and codecs and is known for fast video processing.\n\n```python\n# load the video file\nvf = VideoFile().from_file(\"test_files/test_vid_1.mp4\")\n\n# extract audio_file\nvf.extract_audio(\"extracted_audio.mp3\")\n\n# stream the video\nfor img, audio in vf.to_video_stream(include_audio=True):\n    cv2.imwrite(\"outtest.png\", img)\n\n# add audio to an videofile (supports files and numpy.array)\nvf.add_audio(\"path/to/audio.mp3\")\n\n# create a video from a folder\nVideoFile().from_dir(\"path/to/image_folder\", audio=f\"extracted_audio.mp3\", frame_rate=30)\n\n# create a video from a video stream\nfromstream = VideoFile().from_video_stream(vf.to_video_stream(include_audio=True))\n```\n\n## Web-features\n\nWe intent to make transmitting files between services as easy as possible.\nHere are some examples for services and clients.\n\n### FastTaskAPI - Services\nThe library supports the FastTaskAPI and FastSDK for easy file transmission between services.\nSimply use the files in the task_endpoint function definition and transmitted data will be converted.\nCheck out the [FastTaskAPI]() documentation for more information.\n```python\nfrom fast_task_api import ImageFile, AudioFile, VideoFile\n\n@app.task_endpoint(\"/my_file_upload\")\ndef my_upload_image(image: ImageFile, audio: AudioFile, video: VideoFile):\n    image_as_np_array = np.array(image)\n```\n\n### fastAPI - services\nYou can use the files in fastapi and transform the starlette upload file to a MediaFile.\n```python\n@app.post(\"/upload\")\nasync def upload_file(file: UploadFile = File(...)):\n    mf = ImageFile().from_starlette_upload_file(file)\n    return {\"filename\": file.filename}\n```\n\n### Client with: requests, httpx\nTo send a MediaFile to an openapi endpoint you can use the following method:\n\n```python\nimport httpx\n\nmy_media_file = ImageFile().from_file(\"path/to/my_image.png\")\nmy_files = {\n  \"param_name\": my_media_file.to_httpx_send_able_tuple()\n  ...\n}\nresponse = httpx.Client().post(url, files=my_files)\n```\n\n\n# How it works\n\nIf media-file is instantiated with ```from_*``` it converts it to an intermediate representation.\nThe ```to_*``` methods then convert it to the desired format.\n\nCurrently the intermediate representation is supported in memory with (BytesIO).\n\n\n# ToDo:\n\n- [x] additionally support tempfile backend instead of working bytesio memory mode only.\n- [x] decreasing redundancies for _file_info() method","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocaity%2Fmedia-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocaity%2Fmedia-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocaity%2Fmedia-toolkit/lists"}