{"id":13621202,"url":"https://github.com/cshum/imagorvideo","last_synced_at":"2026-01-03T19:14:37.426Z","repository":{"id":58963014,"uuid":"534207002","full_name":"cshum/imagorvideo","owner":"cshum","description":"imagor video thumbnail server in Go and ffmpeg C bindings","archived":false,"fork":false,"pushed_at":"2024-08-31T00:33:40.000Z","size":10125,"stargazers_count":179,"open_issues_count":6,"forks_count":13,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-15T22:13:37.595Z","etag":null,"topics":["docker","ffmpeg","flv","mkv","mp4","ogg","rmse","thumbnail","webm"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cshum.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":"cshum"}},"created_at":"2022-09-08T12:42:23.000Z","updated_at":"2024-10-15T12:25:04.000Z","dependencies_parsed_at":"2024-06-19T06:13:02.681Z","dependency_job_id":"e233d295-aab5-4c81-b422-a5f2ee41ab57","html_url":"https://github.com/cshum/imagorvideo","commit_stats":{"total_commits":138,"total_committers":2,"mean_commits":69.0,"dds":"0.021739130434782594","last_synced_commit":"b5cd3b64cb58db0c5e81d3d15b778e900649867c"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cshum%2Fimagorvideo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cshum%2Fimagorvideo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cshum%2Fimagorvideo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cshum%2Fimagorvideo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cshum","download_url":"https://codeload.github.com/cshum/imagorvideo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248694049,"owners_count":21146919,"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":["docker","ffmpeg","flv","mkv","mp4","ogg","rmse","thumbnail","webm"],"created_at":"2024-08-01T21:01:03.557Z","updated_at":"2026-01-03T19:14:37.421Z","avatar_url":"https://github.com/cshum.png","language":"Go","funding_links":["https://github.com/sponsors/cshum"],"categories":["HarmonyOS","Go","🤖 AI \u0026 Machine Learning"],"sub_categories":["Windows Manager"],"readme":"# imagorvideo\n\n[![Test Status](https://github.com/cshum/imagorvideo/workflows/test/badge.svg)](https://github.com/cshum/imagorvideo/actions/workflows/test.yml)\n[![Coverage Status](https://img.shields.io/coverallsCoverage/github/cshum/imagorvideo)](https://coveralls.io/github/cshum/imagorvideo?branch=master)\n[![Docker Hub](https://img.shields.io/badge/docker-shumc/imagorvideo-blue.svg)](https://hub.docker.com/r/shumc/imagorvideo/)\n\nimagorvideo is a new initiative that brings video thumbnail capability through ffmpeg, built on the foundations of [imagor](https://github.com/cshum/imagor) - a fast, secure image processing server and Go library, using libvips.\n\nimagorvideo uses ffmpeg C bindings that extracts video thumbnail by selecting the best frame from a RMSE histogram. It then goes through the rest of imagor pipeline to perform image [cropping, resizing](https://github.com/cshum/imagor#image-endpoint) and [filters](https://github.com/cshum/imagor#filters).\n\nimagorvideo implements ffmpeg read and seek I/O callbacks with imagor [loader, storage and result storage](https://github.com/cshum/imagor#loader-storage-and-result-storage), which supports HTTP(s), File System, AWS S3 and Google Cloud Storage out of box. For non seek-able source such as HTTP and S3, imagor simulates seek using memory or temp file buffer.\n\nThis also aims to be a reference project demonstrating imagor extension.\n\n### Quick Start\n\n```bash\ndocker run -p 8000:8000 shumc/imagorvideo -imagor-unsafe\n```\n\nOriginal:\n```\nhttp://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\n```\n\nResult:\n```\nhttp://localhost:8000/unsafe/300x0/7x7/filters:label(imagorvideo,-10,-7,15,yellow):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\nhttp://localhost:8000/unsafe/300x0/0x0:0x14/filters:frame(1m59s):fill(yellow):label(imagorvideo,center,bottom,12,black,20)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\nhttp://localhost:8000/unsafe/300x0/7x7/filters:frame(0.6):label(imagorvideo,10,-7,15,yellow):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/demo.jpg\" height=\"150\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/demo2.jpg\" height=\"150\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/demo3.jpg\" height=\"150\" /\u003e \n\nimagorvideo works by streaming out a limited number of frame data, looping through and calculating the histogram of each frame. It then choose the best frame based on Root Mean Square Error (RMSE). This allow skipping the black frames that usually occur at the beginning of videos. \n\nimagorvideo then converts the selected frame to RGB image data, forwards to the imagor libvips processor, which has always been best at image processing with tons of features. Check out imagor [endpoint](https://github.com/cshum/imagor#image-endpoint) and [security](https://github.com/cshum/imagor#security) for image operations supported.\n\n### Filters\n\nimagorvideo supports the following filters, which can be used in conjunction with [imagor filters](https://github.com/cshum/imagor#filters):\n\n- `frame(n)` specify the position or time duration for imaging, which skips the automatic best frame selection:\n  - Float between `0.0` and `1.0` position index of the video. Example `frame(0.5)`, `frame(1.0)`\n  - Time duration of the elapsed time since the start of video. Example `frame(5m1s)`, `frame(200s)`\n- `seek(n)` seeks to the approximate position or time duration, then perform automatic best frame selection around that point:\n  - Float between `0.0` and `1.0` position index of the video. Example `seek(0.5)`\n  - Time duration of the elapsed time since the start of video. Example `seek(5m1s)`, `seek(200s)`\n- `max_frames(n)` restrict the maximum number of frames allocated for image selection. The smaller the number, the faster the processing time.\n\n#### `frame(n)` vs `seek(n)`\n\nThere are differences you may want to choose one over the other.\n`frame(n)` gives you the precise time frame specified. However, precise may not be the best in some circumstances:\n```\nhttp://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\n```\nRetrieving the frame at 5 minutes elapsed time of this video:\n```\nhttp://localhost:8000/unsafe/filters:frame(5m)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\n```\nIt results a complete black frame. \n\n![black](https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/black.jpg)\n\nThis is where `seek(n)` comes handy. It seeks to the key frame before the 5 minutes elapsed time, then perform best frame selection starting from that point using Root Mean Square Error (RMSE) histogram.\nThe result is a reasonable image that sits close to the specified time:\n\n```\nhttp://localhost:8000/unsafe/filters:seek(5m)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\n```\n![seek 5m](https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/seek5m.jpg)\n\n### Metadata\n\nimagorvideo provides metadata endpoint that extracts video metadata, including dimension, duration and FPS data. It processes header only, without extracting the frame data for better processing speed.\n\nTo use the metadata endpoint, add `/meta` right after the URL signature hash before the image operations:\n\n```\nhttp://localhost:8000/unsafe/meta/https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_30MB.mp4\n```\n\n```jsonc\n{\n  \"format\": \"mp4\",\n  \"content_type\": \"video/mp4\",\n  \"orientation\": 1,\n  \"duration\": 10000,\n  \"width\": 1920,\n  \"height\": 1080,\n  \"title\": \"Big Buck Bunny, Sunflower version\",\n  \"artist\": \"Blender Foundation 2008, Janus Bager Kristensen 2013\",\n  \"fps\": 30,\n  \"has_video\": true,\n  \"has_audio\": false\n}\n```\n\n### Configuration\n\nConfiguration options specific to imagorvideo. Please see [imagor configuration](https://github.com/cshum/imagor#configuration) for all existing options available.\n\n```\n  -ffmpeg-fallback-image string\n        FFmpeg fallback image on processing error. Supports image path enabled by loaders or storages\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcshum%2Fimagorvideo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcshum%2Fimagorvideo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcshum%2Fimagorvideo/lists"}