{"id":13906568,"url":"https://github.com/tjenkinson/hls-live-thumbnails","last_synced_at":"2025-04-06T12:09:31.535Z","repository":{"id":9837046,"uuid":"62921575","full_name":"tjenkinson/hls-live-thumbnails","owner":"tjenkinson","description":"A service which will generate thumbnails from a live HLS stream.","archived":false,"fork":false,"pushed_at":"2024-12-10T19:12:07.000Z","size":986,"stargazers_count":64,"open_issues_count":16,"forks_count":14,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T11:07:23.980Z","etag":null,"topics":["cli","generating-thumbnails","hls","hls-live-streaming","hls-live-thumbnails","hls-stream","playlist","service","standalone","thumbnail","thumbnails"],"latest_commit_sha":null,"homepage":null,"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/tjenkinson.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-08T22:45:41.000Z","updated_at":"2024-06-17T12:47:06.000Z","dependencies_parsed_at":"2024-01-19T10:12:21.962Z","dependency_job_id":"ca7d5235-4f6c-43ea-a434-504aca30cb70","html_url":"https://github.com/tjenkinson/hls-live-thumbnails","commit_stats":{"total_commits":90,"total_committers":6,"mean_commits":15.0,"dds":0.5444444444444445,"last_synced_commit":"cac9c52f31f02dce500d738bb89d562a62fb3294"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjenkinson%2Fhls-live-thumbnails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjenkinson%2Fhls-live-thumbnails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjenkinson%2Fhls-live-thumbnails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjenkinson%2Fhls-live-thumbnails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tjenkinson","download_url":"https://codeload.github.com/tjenkinson/hls-live-thumbnails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478323,"owners_count":20945266,"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":["cli","generating-thumbnails","hls","hls-live-streaming","hls-live-thumbnails","hls-stream","playlist","service","standalone","thumbnail","thumbnails"],"created_at":"2024-08-06T23:01:38.434Z","updated_at":"2025-04-06T12:09:31.515Z","avatar_url":"https://github.com/tjenkinson.png","language":"JavaScript","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"[![npm version](https://img.shields.io/npm/v/hls-live-thumbnails.svg?maxAge=2592000)](https://www.npmjs.com/package/hls-live-thumbnails)\n[![npm](https://img.shields.io/npm/dm/hls-live-thumbnails.svg?maxAge=2592000)](https://www.npmjs.com/package/hls-live-thumbnails)\n[![npm](https://img.shields.io/npm/dt/hls-live-thumbnails.svg?maxAge=2592000)](https://www.npmjs.com/package/hls-live-thumbnails)\n# HLS Live Thumbnails\nA service which will generate thumbnails from a live HLS stream.\n\nCan be either used as a library, run as a service and controlled with http requests, or standalone for handling a single stream.\n\n### Installation\n- Install [ffmpeg](https://ffmpeg.org/download.html) globally. You should be able to simply `ffmpeg` at a command prompt.\n- `npm install -g hls-live-thumbnails` to install globally.\n\n### Demo\nRun `hls-live-thumbnails https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8`.\n\n### ThumbnailGenerator\nThis will generate thumbnails from a HLS stream and emit a `newThumbnail` event whenever a thumbnail is generated.\n\n### SimpleThumbnailGenerator\nThis uses `ThumbnailGenerator` but will also remove thumbnails when their segments are removed from the playlist, or when the playlist no longer exists.\nYou can configure a time to wait before removing thumbnails after their segments are removed using the `expireTime` option.\nThis generates a JSON manifest file with information about the generated thumbnails.\n\nIf you never want the manifest or thumbnails to be deleted use the `neverDelete` option.\n\n### Service \u0026 Standalone\nYou can run this as a service which will expose a http API for control, or standalone.\n\nIf run standalone the program will terminate with exit code 0 once all thumbnails have been generated and the stream has ended, or 1 if there was an error.\n\nThese are the options:\n- **url**: The URL of the stream. If specified 'port' or 'secret' must not be provided.\n- **manifestFileName**:  The name of the manifest file. Only valid with 'url' option and defaults to 'thumbnails.json'.\n- **outputNamePrefix**: The string to be prefixed to the thumbnail file names. Only valid with 'url' option and defaults to a hash of the stream URL.\n- **port**: The port to listen on. Defaults to 8080, unless running standalone.\n- **pingInterval**: If a ping request isn't made every 'pingInterval' seconds then thumbnail generation will stop. Defaults to disabled.\n- **clearOutputDir**: If provided the output directory will be emptied when the program starts.\n- **outputDir**: The directory to place the thumbnails and manifest file.\n- **tempDir**: A directory to use for temporary files. (Optional)\n- **secret**: A string which must be provided in a \"x-secret\" header for each request.\n- **expireTime**: The time in seconds to keep thumbnails for before deleting them, once their segments have left the playlist. Defaults to 0.\n- **neverDelete**: Keep all thumbnails and the manifest around forever. Cannot be used with `expireTime`. Defaults to `false`.\n- **interval**: The default interval between thumbnails. If omitted the interval will be calculated automatically using `targetThumbnailCount`.\n- **initialThumbnailCount**: The default number of thumbnails to generate initially, from the end of the stream. If ommitted defaults to taking thumbnails for the entire stream.\n- **targetThumbnailCount**: The default number of thumbnails that should be generated over the duration of the stream. Defaults to 30. This will be recalculated if the stream duration changes.\n- **width**: The default width of the thumbnails to generate (px). If omitted this will be calculated automatically from the height, or default to 150.\n- **height**: The default height of the thumbnails to generate (px). If omitted this will be calculated automatically from the width.\n- **ignorePlaylist404**: Do not abort immediately if the playlist response is a 404. Defaults to false.\n- **playlistRetryCount**: The number of times to retry downloding the playlist on an error. Defaults to 2. Can be -1 for unlimited retries.\n\nE.g. Service: `hls-live-thumbnails --secret \"super-secret\" --targetThumbnailCount 20 --width 300`\nE.g. Standalone: `hls-live-thumbnails https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8  --width 300`\n\n#### API\n##### POST /v1/start\nStart generating thumbnails for a stream.\n\nThe following parameters are allowed:\n- **url**: The playlist URL. (Requierd)\n- **width**: Override `width` option. (Optional)\n- **height**: Override `height` option. (Optional)\n- **interval**: Override `interval` option. (Optional)\n- **initialThumbnailCount**: Override `initialThumbnailCount` option. (Optional)\n- **targetThumbnailCount**: Override `targetThumbnailCount` option. (Optional)\n- **id**: Provide an alpha-numeric ID for this generator. (Optional. Will be generated automatically if not provided.)\n\nThe response is `{id: \u003cid which represents this generator\u003e}`\n\nThe manifest file will be called \"thumbnails-[id].json\".\n\n##### GET /v1/generators/:id\nGet information about the provided generator. A 404 will be returned if a generator no longer exists, e.g. if all thumbnails have expired.\n\nThe response is `{ended: \u003ctrue if the stream has ended, no more thumbnails will be generated\u003e}`\n\nThis counts as a 'ping'. Look at the 'pingInterval' option.\n\n##### DELETE /v1/generators/:id\nTerminate the generator with `id`. All of its thumbnails will be removed.\n\n### Manifest File Format\nThis is the structure of the manifest file. It will be called \"thumbnails-[id].json\".\n```\n{\n  \"ended\":\u003ctrue if the stream has ended\u003e,\n  \"segments\": [{\n    \"sn\": \u003csegment sequence number\u003e,\n    \"removalTime\": \u003cThe time the segment was removed from the playlist, or null\u003e,\n    \"thumbnails\": [\n      {\n        time: \u003ctime into the segment that the thumbnail was taken (seconds)\u003e,\n        name: \u003cthumbnail filename\u003e\n      },\n      {\n        time: \u003ctime into the segment that the thumbnail was taken (seconds)\u003e,\n        name: \u003cthumbnail filename\u003e\n      }\n    ]\n  }]\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjenkinson%2Fhls-live-thumbnails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftjenkinson%2Fhls-live-thumbnails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjenkinson%2Fhls-live-thumbnails/lists"}