Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tjenkinson/hls-live-thumbnails
A service which will generate thumbnails from a live HLS stream.
https://github.com/tjenkinson/hls-live-thumbnails
cli generating-thumbnails hls hls-live-streaming hls-live-thumbnails hls-stream playlist service standalone thumbnail thumbnails
Last synced: about 2 months ago
JSON representation
A service which will generate thumbnails from a live HLS stream.
- Host: GitHub
- URL: https://github.com/tjenkinson/hls-live-thumbnails
- Owner: tjenkinson
- License: mit
- Created: 2016-07-08T22:45:41.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-05-20T08:43:27.000Z (5 months ago)
- Last Synced: 2024-07-27T15:44:07.921Z (2 months ago)
- Topics: cli, generating-thumbnails, hls, hls-live-streaming, hls-live-thumbnails, hls-stream, playlist, service, standalone, thumbnail, thumbnails
- Language: JavaScript
- Size: 791 KB
- Stars: 64
- Watchers: 5
- Forks: 15
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/hls-live-thumbnails)
[](https://www.npmjs.com/package/hls-live-thumbnails)
[](https://www.npmjs.com/package/hls-live-thumbnails)
# HLS Live Thumbnails
A service which will generate thumbnails from a live HLS stream.
Can be either used as a library, run as a service and controlled with http requests, or standalone for handling a single stream.
### Installation
- Install [ffmpeg](https://ffmpeg.org/download.html) globally. You should be able to simply `ffmpeg` at a command prompt.
- `npm install -g hls-live-thumbnails` to install globally.
### Demo
Run `hls-live-thumbnails https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8`.
### ThumbnailGenerator
This will generate thumbnails from a HLS stream and emit a `newThumbnail` event whenever a thumbnail is generated.
### SimpleThumbnailGenerator
This uses `ThumbnailGenerator` but will also remove thumbnails when their segments are removed from the playlist, or when the playlist no longer exists.
You can configure a time to wait before removing thumbnails after their segments are removed using the `expireTime` option.
This generates a JSON manifest file with information about the generated thumbnails.
If you never want the manifest or thumbnails to be deleted use the `neverDelete` option.
### Service & Standalone
You can run this as a service which will expose a http API for control, or standalone.
If 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.
These are the options:
- **url**: The URL of the stream. If specified 'port' or 'secret' must not be provided.
- **manifestFileName**: The name of the manifest file. Only valid with 'url' option and defaults to 'thumbnails.json'.
- **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.
- **port**: The port to listen on. Defaults to 8080, unless running standalone.
- **pingInterval**: If a ping request isn't made every 'pingInterval' seconds then thumbnail generation will stop. Defaults to disabled.
- **clearOutputDir**: If provided the output directory will be emptied when the program starts.
- **outputDir**: The directory to place the thumbnails and manifest file.
- **tempDir**: A directory to use for temporary files. (Optional)
- **secret**: A string which must be provided in a "x-secret" header for each request.
- **expireTime**: The time in seconds to keep thumbnails for before deleting them, once their segments have left the playlist. Defaults to 0.
- **neverDelete**: Keep all thumbnails and the manifest around forever. Cannot be used with `expireTime`. Defaults to `false`.
- **interval**: The default interval between thumbnails. If omitted the interval will be calculated automatically using `targetThumbnailCount`.
- **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.
- **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.
- **width**: The default width of the thumbnails to generate (px). If omitted this will be calculated automatically from the height, or default to 150.
- **height**: The default height of the thumbnails to generate (px). If omitted this will be calculated automatically from the width.
- **ignorePlaylist404**: Do not abort immediately if the playlist response is a 404. Defaults to false.
- **playlistRetryCount**: The number of times to retry downloding the playlist on an error. Defaults to 2. Can be -1 for unlimited retries.
E.g. Service: `hls-live-thumbnails --secret "super-secret" --targetThumbnailCount 20 --width 300`
E.g. Standalone: `hls-live-thumbnails https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8 --width 300`
#### API
##### POST /v1/start
Start generating thumbnails for a stream.
The following parameters are allowed:
- **url**: The playlist URL. (Requierd)
- **width**: Override `width` option. (Optional)
- **height**: Override `height` option. (Optional)
- **interval**: Override `interval` option. (Optional)
- **initialThumbnailCount**: Override `initialThumbnailCount` option. (Optional)
- **targetThumbnailCount**: Override `targetThumbnailCount` option. (Optional)
- **id**: Provide an alpha-numeric ID for this generator. (Optional. Will be generated automatically if not provided.)
The response is `{id: }`
The manifest file will be called "thumbnails-[id].json".
##### GET /v1/generators/:id
Get information about the provided generator. A 404 will be returned if a generator no longer exists, e.g. if all thumbnails have expired.
The response is `{ended: }`
This counts as a 'ping'. Look at the 'pingInterval' option.
##### DELETE /v1/generators/:id
Terminate the generator with `id`. All of its thumbnails will be removed.
### Manifest File Format
This is the structure of the manifest file. It will be called "thumbnails-[id].json".
```
{
"ended":,
"segments": [{
"sn": ,
"removalTime": ,
"thumbnails": [
{
time: