{"id":17858483,"url":"https://github.com/sintef-9012/caracal","last_synced_at":"2025-03-20T16:32:37.386Z","repository":{"id":15824624,"uuid":"18564433","full_name":"SINTEF-9012/Caracal","owner":"SINTEF-9012","description":"Light multimedia web server designed as a service","archived":false,"fork":false,"pushed_at":"2017-07-03T12:35:50.000Z","size":127,"stargazers_count":10,"open_issues_count":0,"forks_count":11,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-15T22:33:34.335Z","etag":null,"topics":["ffmpeg","file-upload","imagemagick","multimedia","pictures","resize-images","resize-videos","rest-api","videos"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SINTEF-9012.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-08T15:52:27.000Z","updated_at":"2023-01-12T02:12:13.000Z","dependencies_parsed_at":"2022-08-25T11:50:50.946Z","dependency_job_id":null,"html_url":"https://github.com/SINTEF-9012/Caracal","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF-9012%2FCaracal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF-9012%2FCaracal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF-9012%2FCaracal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SINTEF-9012%2FCaracal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SINTEF-9012","download_url":"https://codeload.github.com/SINTEF-9012/Caracal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244650062,"owners_count":20487554,"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":["ffmpeg","file-upload","imagemagick","multimedia","pictures","resize-images","resize-videos","rest-api","videos"],"created_at":"2024-10-28T05:07:14.456Z","updated_at":"2025-03-20T16:32:37.380Z","avatar_url":"https://github.com/SINTEF-9012.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Caracal\n=======\n\nCaracal is a light multimedia server designed as a service.\n\nIt provides a simple HTTP REST API and a HTML5 user interface.\n\n### Installation\n```npm install caracal```\n\n_GraphicsMagick or ImageMagick is required. FFmpeg (not libav) is necessary for video resizing and converting._\n\n### [Docker](https://registry.hub.docker.com/u/yellowiscool/caracal/)\n\n```sh\ndocker pull yellowiscool/caracal\n\ndocker volume create --name caracal-data\n\ndocker run -d --restart=always \\\n  --name caracal \\\n  -v caracal-data:/usr/src/app/data \\\n  -e DELETIONS_KEY=secretkey \\\n  yellowiscool/caracal\n```\n\n\n### Features\n\n * File uploads\n * File suppressions\n * Picture and video thumbnails\n * Picture resizing\n * Video resizing and converting\n  * Convert videos to H264 or Webm \n * Can fetch distant HTTP files\n  * Multimedia reverse proxy with a cache\n  * Transparent resizing\n  * Transparent video converting\n  * Basic HTTP authentification support\n * Light HTML5 user interface\n  * Drag and drop support\n  * Progression bar for slow connexions\n  * Thumbnails and pagination\n * Configurable generation of identifiers\n  * human readable\n  * adjective-adjective-animal\n  * shortid\n  * sha256\n\n### Notes about the scalability\n\nCaracal is designed to run as a single node on a single server. It does not support horizontal scaling. It is suitable for prototyping or simple non-critical multimedia applications, but it cannot be used to compete with Youtube or Imgur (yet). In case of a high load, a processing queue is used.\n\n## Configuration\n\nCaracal can be configured using environment variables.\n\n|Environment Variable|Description|Default value|\n|--------------------|-----------|-------------|\n|DELETIONS_KEY|The required password/key to delete files.|*needs to be configured*|\n|ALLOWED_DOMAINS|Optionnal JSON array of allowed domains, for [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)|`*` (all domains are allowed)|\n|HTTP_PORT|Listening HTTP port|8075|\n|DATAPATH|Location of the storage folder|`./data`|\n|CACHE|[HTTP Cache-Control header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9)|`max-age=29030400, public`|\n|CONCURRENCY|Number of allowed concurrent image processing tasks|8|\n|VIDEO_CONCURRENCY|Number of allowed concurrent video processing tasks|2|\n|ALLOWED_SIZES|Array of allowed resizing sizes. If a requested size is not found, the closest size from this array is used instead. Set to `*` to allow every size, but it's not recommended since users can saturate the server by resizing the same image many times. The default configuration allows many sizes, you might want to use fewer sizes.|`[32, 64, 128, 256, 1024, 2048, 4096, 8192, 16384,\t50, 100, 200, 400, 500, 600, 800, 1000, 1050, 1200, 1600, 120, 160, 240, 320, 480, 576, 640, 768, 854, 960, 1050, 1080, 1152, 1280, 1440, 1536,  1716, 1920, 2160, 2560, 3200,\t3840, 3996, 4320, 4800, 5120, 6400, 6144, 7680, 12288]`|\n|ALLOWED_VIDEO_SIZES|Array of allowed resizing sizes, for videos. Similar to ALLOWED_SIZES.|`[144, 240, 360, 480, 720, 1080, 3840]`|\n|AUTHS|JSON association table (object) used for HTTP [basic access authentications](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side), when fetching distant files. keys are the host-names, values are the passwords.|`{}`|\n|UA|The HTTP client user agent, to fetch distant files|~Firefox28-Win64|\n|IDS_GENERATION|The algorithm used to generate identifiers. See the generation of identifiers section. Accepted values are sillyid, shortid, human-readable, bronze, and hash.|sillyid|\n\n## API\n\n#### GET /\n\nHTML5 user interface.\n\n#### GET /files\n\nJSON list of files stored in the server\n```json\n[\n {\n    \"url\": \"http://upload.wikimedia.org/wikipedia/commons/d/d3/Veymont-aiguille_mg-k.jpg\",\n    \"name\": \"Veymont-aiguille_mg-k.jpg\",\n    \"id\": \"ElementaryPertinentWalleye\",\n    \"size\": 168454,\n    \"hash\": \"698baa587aef2a26bddd8461d6a4e132ae1dcbd5f58aa6e47c20bc703356a8ec\",\n    \"extension\": \"jpeg\",\n    \"type\": \"image/jpeg\",    \n    \"mtime\": \"2014-04-09T11:36:05.145Z\"\n  },...\n]\n```\n\n#### POST /upload\n\nSave on the server the provided file\n```json\n{\n  \"name\": \"208T16-05E.jpg\",\n  \"id\": \"HauntingWholeEsok\",\n  \"size\": 4700,\n  \"status\": \"ok\",\n  \"hash\": \"7d15d97340aaf30e08baf92e9e3aa57b969f12540805be265dee44496f4b099f\",\n  \"extension\": \"png\",\n  \"type\": \"image/png\",\n  \"mtime\": \"2017-02-25T11:49:29.002Z\",\n  \"status\": \"ok\"\n}\n```\n\n#### GET /{URL}\n\nIf the URL is not in the cache, fetch, save and return the content of the url.\n\nExample : ```GET /http://perdu.com```\n\n#### GET /fetch/{URL}\n\nIf the URL is not in the cache fetch and save the content of the url. Then return information about the URL.\n\nResponse example :\n```json\n{\n  \"url\":\"http://perdu.com\",\n  \"name\":\"perdu.com\",\n  \"id\":\"UnacceptableJoyfulLacewing\",\n  \"size\":204,\n  \"hash\":\"208e330c75ffd93949be0258660973bef8223917f036325020f3a4c51b4ca430\",\n  \"extension\":\"html\",\n  \"type\":\"text/html\",\n  \"mtime\":\"2017-02-25T11:52:58.522Z\",\n  \"status\":\"ok\"\n}\n```\n\n#### GET /remove/{hash}.{extension}\n#### GET /remove/{id}\n\nRemove the related files to the hash and the extension from the server.\n\nExamples : \n\n * ```GET /remove/698baa587aef2a26bddd8461d6a4e132ae1dcbd5f58aa6e47c20bc703356a8ec.jpeg```\n * ```GET /remove/ElementaryPertinentWalleye```\n\n#### GET /thumbnail/{hash}.{extension}\n#### GET /thumbnail/{id}\n\nCreate and return a 128x128 thumbnail of the given file. If the format is not supported by GraphicsMagic, an error is returned.\n\nExamples :\n\n * ```GET /thumbnail/698baa587aef2a26bddd8461d6a4e132ae1dcbd5f58aa6e47c20bc703356a8ec.jpeg```\n * ```GET /thumbnail/ElementaryPertinentWalleye```\n\n#### GET /resize/{max_width}/{max_height}/{hash}.{extension}\n#### GET /resize/{max_width}/{max_height}/{id}\n\nResize the given image. The image aspect ratio is conserved.\n\nThe image format must be compatible with GraphicsMagick.\n\nExamples :\n\n * ```GET /resize/1280/720/698baa587aef2a26bddd8461d6a4e132ae1dcbd5f58aa6e47c20bc703356a8ec.jpeg```\n * ```GET /resize/1280/720/ElementaryPertinentWalleye```\n\n#### GET /resize/deform/{max_width}/{max_height}/{hash}.{extension}\n#### GET /resize/deform/{max_width}/{max_height}/{id}\n\nSame as resize but the ratio is not conserved.\n\n#### GET /convert/{format}/{height}/{hash}.{extension}\n#### GET /convert/{format}/{height}/{id}\n\nResize the given video. The video aspect ratio is conserved.\n\nThe input video format must be compatible with your FFmpeg installation.\n\nSupported output formats : mp4 or webm\nSupported output sizes : 240, 480, 720, 1080\n\nExamples :\n\n * ```GET /convert/mp4/720/e7c7c984066753d5cc52e97f26f4f7892df67bacb.wmv```\n * ```GET /convert/mp4/720/WiryRosyQueensnake```\n\n#### GET /thumbnail/{URL}\n\nCreate and return a 128x128 thumbnail of the distant image.\n\nExample : ```GET /thumbnail/http://upload.wikimedia.org/wikipedia/commons/d/d3/Veymont-aiguille_mg-k.jpg```\n\n#### GET /resize/{max_width}/{max_height}/{URL}\n\nResize the distant image. The image aspect ratio is conserved.\n\nExample : ```GET /resize/1280/720/http://upload.wikimedia.org/wikipedia/commons/d/d3/Veymont-aiguille_mg-k.jpg```\n\n#### GET /resize/deform/{max_width}/{max_height}/{URL}\n\nSame as resize but the ratio is not conserved.\n\n#### GET /convert/{format}/{height}/{URL}\n\nResize the distant video. The video ratio is conserved.\n\nThe input video format must be compatible with your FFmpeg installation.\n\nSupported output formats : mp4 or webm\nSupported output sizes : 240, 480, 720, 1080\n\nExample : ```GET /convert/webm/480/http://example.net/video.flv```\n\n#### GET /{hash}.{extension}\n#### GET /{id}\n\nReturn the file :-)\n\n## Behind\n\n * [NodeJs](http://nodejs.org/)\n * [GraphicsMagick](http://www.graphicsmagick.org/) or [ImageMagick](https://www.imagemagick.org/) with [gm](http://aheckmann.github.io/gm/)\n * [FFmpeg](https://www.ffmpeg.org/) with [node-fluent-ffmpeg](https://github.com/fluent-ffmpeg/node-fluent-ffmpeg)\n * [Express](http://expressjs.com/)\n * [Bootstrap](http://getbootstrap.com)\n * [jQuery](http://jquery.com)\n * [jQuery File Upload](http://blueimp.github.io/jQuery-File-Upload/)\n * [NeDB](https://github.com/louischatriot/nedb)\n\n\n## Generation of Identifiers\n\n|Name|Description|Example|\n|----|-----------|-------|\n|[sillyid](https://github.com/Jamesford/SillyId) *(default)*|Generation of fun gfycat like identifiers, following the AdjectiveAdjectiveAnimal pattern.|`HairyOrangeGeckos`|\n|[shortid](https://github.com/dylang/shortid)|Short url-friendly identifiers.|`PPBqWA9`|\n|[human-readable](https://github.com/coolaj86/human-readable-ids-js)|Easy to spell identifiers, following the adjective-noun-# pattern.|`tricky-chicken-23`\n|[bronze](https://github.com/altusaero/bronze)|Collision-resistant ids for distributed systems.|`1482810226160-0-14210-example-1a`|\n|hash|Use the sha256 checksum as id.|`698baa587aef2a26bddd8461d6a4e132ae1dcbd5f58aa6e47c20bc703356a8ec`|\n\n## Screenshot (work in progress)\n\n![Old screenshot](http://i.imgur.com/vydii2e.png)\n\n### Acknowledgements\n\nCaracal is developed in context of the [BRIDGE](http://www.bridgeproject.eu/en) and [HUMANE](https://humane2020.eu/) European research projects.\n\n### Licence\n\nThe source code of this library is licenced under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsintef-9012%2Fcaracal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsintef-9012%2Fcaracal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsintef-9012%2Fcaracal/lists"}