tjenkinson / hls-live-thumbnails

A service which will generate thumbnails from a live HLS stream.

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 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: <id which represents this generator>}

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: <true if the stream has ended, no more thumbnails will be generated>}

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":<true if the stream has ended>,
  "segments": [{
    "sn": <segment sequence number>,
    "removalTime": <The time the segment was removed from the playlist, or null>,
    "thumbnails": [
      {
        time: <time into the segment that the thumbnail was taken (seconds)>,
        name: <thumbnail filename>
      },
      {
        time: <time into the segment that the thumbnail was taken (seconds)>,
        name: <thumbnail filename>
      }
    ]
  }]
}

hls-live-thumbnails's Issues

npm global install not working

npm install -g hls-live-thumbnails to install globally is not working

I also tried with sudo but it doesn't work

Error installing

Hi,

I'm having an error installing your extension, the log is below:

npm ERR! Error while executing:
npm ERR! /usr/bin/git ls-remote -h -t ssh://[email protected]/tjenkinson/node-m3u8.git
npm ERR!
npm ERR! fatal: Cannot change to '/root/teste/..': Permission denied
npm ERR!
npm ERR! exited with error code: 128

npm ERR! A complete log of this run can be found in:
npm ERR! /root/.npm/_logs/2017-10-07T12_47_54_243Z-debug.log

Overwrite Thumbnails

Is there a way to only generate one thumbnail, that will be overwritten continuously?

Error On Install

Tried to install inside a Docker Container with running Ubuntu. Got this errror

npm ERR! Error: No compatible version found: m3u8@'github:tjenkinson/node-m3u8#hls-live-thumbnails'
npm ERR! Valid install targets:
npm ERR! ["0.0.1","0.0.2","0.0.3","0.0.4","0.0.5","0.0.6","0.0.7"]
npm ERR!     at installTargetsError (/usr/share/npm/lib/cache.js:719:10)
npm ERR!     at /usr/share/npm/lib/cache.js:638:10
npm ERR!     at saved (/usr/share/npm/node_modules/npm-registry-client/lib/get.js:142:7)
npm ERR!     at /usr/lib/nodejs/graceful-fs/polyfills.js:133:7
npm ERR!     at Object.oncomplete (fs.js:107:15)
npm ERR! If you need help, you may report this log at:
npm ERR!     <http://github.com/isaacs/npm/issues>
npm ERR! or email it to:
npm ERR!     <[email protected]>

npm ERR! System Linux 4.4.27-moby
npm ERR! command "/usr/bin/nodejs" "/usr/bin/npm" "install" "-g" "hls-live-thumbnails@latest"
npm ERR! cwd /
npm ERR! node -v v0.10.25
npm ERR! npm -v 1.3.10
npm http 200 https://registry.npmjs.org/fluent-ffmpeg/-/fluent-ffmpeg-2.1.0.tgz
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     /npm-debug.log
npm ERR! not ok code 0

Bug: Width and height arguments not working.

I am trying to generated thumbnails from my hls livestream. I use the following command:

hls-live-thumbnails https://live.api.video/li2fnO5UQJpsoGwDM9r4NeIy.m3u8 --width 300 --targetThumbnailCount 1

The generated thumbnail is 150x84 pixel, which is the default value. Using height does not work either.

Thanks for the help!
Bernard

Error when temp directory on different drive

Error: EXDEV: cross-device link not permitted, rename

Should perform a copy and delete in this case instead.

event "finished" never get fired

I try to implement this in nest js but I found that only event "playlistEnded" get called but it was always one thumbnails behind I try to read the source code but seem to not able to find why it never get called. all the thumbnails and manifest generated correctly

const generator = new hls.SimpleThumbnailGenerator({
     manifestFileName: `test.json`,
     logger: null
   }, {
     playlistUrl: 'https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8',
     outputDir: `./test/${body.name}`,
     targetThumbnailCount: 30,

   })

generator.getEmitter().on("finished", async () => {}

Background service

Is there any way to run the thumbnail generator service as background?
so after I put something like this hls-live-thumbnails --secret 'supper_secret' on terminal, it will run as a background service, so I can put another command on the same terminal without stopping it

Thumbnail time is completly wrong.

Hi,

I've been trying to use your solution, but for some reason thumbnails "time" seems to be messed up. I've been trying to import the thumbs using clappr thumbnails plugin using the following code:

function addThumbs()
{

var request = $.ajax({
	  url: "/app/myapp/thumbs/<?php echo get_field('stream') ?>/thumbnails.json",
	  type: "GET",
	  dataType: "json"
	});

	request.done(function(retorno) {

		$.each( retorno.segments, function( key, val ) {
				var thumbnailsPlugin = player.getPlugin("scrub-thumbnails");
				var newThumb = {
					url: "/app/myapp/thumbs/<?php echo get_field('stream') ?>/"+val.thumbnails[0].name,
					time: val.thumbnails[0].time
				};
				
				thumbnailsPlugin.addThumbnail(newThumb).then(function() {
					console.log("Thumbnail added."+newThumb.url+" Time: "+val.thumbnails[0].time);
				});
		});
	});
}

setInterval(function(){ addThumbs(); }, 15000); 

addThumbs();

This is part of my generated thumbnails.json:

"segments":[{"sn":0,"thumbnails":[{"time":0,"name":"283ec_recordall-0-0.jpg"}]},{"sn":1,"thumbnails":[{"time":12.134,"name":"283ec_recordall-1-0.jpg"}]},{"sn":2,"thumbnails":[{"time":3.432000000000002,"name":"283ec_recordall-2-0.jpg"}]},{"sn":4,"thumbnails":[{"time":0,"name":"283ec_recordall-4-0.jpg"}]},

Well, as you can see the time is not continuous, it start with 0, then 12 and the next is 3.43.

I'm using NGINX + RTMP plugin to generate the HLS and pointing the .m3u8 as intended.

In my nginx application the hls_fragment is set to 10s

These are the options (in nginx.conf) i'm using to generate the thumbs:
exec bash -c "hls-live-thumbnails http://nginx/app/hls/$name/index.m3u8 --interval 30 --targetThumbnailCount 30 --outputDir /data/app/thumbs/$name --outputNamePrefix $name";

What am I doing wrong ? Am I misunderstanding how your plugin works ?

Rename thumbnail filename

Is there a way to give the thumbnail a spesific filename with number after it?

Add 'exitOnPlaylistEnd' option to CLI

When this is provided the program should exit with status code 0 when it reached the #EXT-X-ENDLIST tag and not delete the thumbnails or manifest file.

Everything else should result in thumbnails and manifest being deleted and exit code 1.

Time Based Interval

Is there any way that I could only create one thumbnail once every 10 seconds? Currently it seems like and endless stream.

node.js promise error

The library option I use is 'hls-live-thumbnails --ignorePlaylist404 --playlistRetryCount-1 --port 8001 --interval 200 --width 360 --height 640 --neverDelete'

The problem occurred when extracting thumbnails from more than one broadcast. The server managed by pm2 has been rebooted due to a promise error in node.js.

The error logs are as follows: Can you help me?

It worked well when we extracted thumbnails from one broadcast.

I have a question

hello.
I am a person who uses the library well.

I am writing because I have a question.

I am creating a thumbnail while performing live streaming with nginx-rtmp, and even if I set the expireTime option to 864000 to not delete it for one day, the thumbnails that are not in progress in real time are deleted. How can I not delete the thumbnails I made before giving the delete command?

Here is my code.

command
hls-live-thumbnails --ignorePlaylist404 --playlistRetryCount -1 --port 8001 --interval 100 --width 300

//create thumbnails
var options = { method: 'POST',
      url: 'http://localhost/v1/start',
      headers: 
      { 
        'cache-control': 'no-cache',
        'content-type': 'application/x-www-form-urlencoded ; charset=UTF-8' },
      form: { url: temp_url, id: temp_rtmp_key ,expireTime : 864000} };
    
    request(options, function (error, response, body) {
      if (error) throw new Error(error);
    
      console.log(body);
    });

Feature request: support byte-range stream (EXT-X-BYTERANGE)

Right now it just creates the same thumbnail each interval cause it believes the single file is a new segment.

A byte range playlist can be created with ffmpeg and the flag single_file.

Ignore Error

Is there a way to ignore error?
So even there's an error, the generator will always running and try to grab the next thumbnail?
Maybe only print the error to log but the generator will not be deleted