hls-transcoder v0.1.3

HLS Transcoder

THIS PACKAGE IS STILL UNDER ACTIVE DEVELOPMENT, API CHANGES CAN AND LIKELY WILL HAPPEN REGARDLESS OF WHETHER THEY ARE DOCUMENTED BELOW

An FFMPEG Wrapper heavily inspired by simple-hls, to transcode Multi-bitrate HLS videos.

Installation:

Via npm:

npm install hls-transcoder

Prerequisites

ffmpeg and ffprobe

hls-transcoder requires both ffmpeg, and ffprobe. If ffmpeg and ffprobe are installed on your system, and added to PATH, hls-transcoder will try invoking each program via ffmpeg and ffprobe respectively.

Alternatively, you can use pre-compiled binaries, ie with @ffmpeg-installer/ffmpeg and @ffprobe-installer/ffprobe, and specify the ffmpegPath and ffprobePath properties in the options object.

Usage:

Basic Setup

Typescript:

import Transcoder from 'hls-transcoder'

async function transcodeVideo() {
  const transcoder = new Transcoder(`[input-video.mp4/.mov/.avi/etc]``${__dirname}/output`)

  transcoder.on('error', (err) => {
    console.error(err)
  })

  try {
    const hlsPath = await transcoder.transcode()
    console.log('Successfully Transcoded Video')
  } catch (err) {
    console.log(err)
  }
}

transcodeVideo()

OR

Use @ffmpeg-installer/ffmpeg and @ffprobe-installer/ffprobe to use precompiled binaries of ffmpeg and ffprobe without having to install on your system.

Typescript:

import Transcoder from 'hls-transcoder'
import ffmpeg from '@ffmpeg-installer/ffmpeg'
import ffprobe from '@ffprobe-installer/ffprobe'

async function transcodeVideo() {
  const transcoder = new Transcoder(`[input-video.mp4/.mov/.avi/etc]``${__dirname}/output`, {
    ffmpegPath: ffmpeg.path,
    ffprobePath: ffprobe.path
  })

  transcoder.on('error', (err) => {
    console.error(err)
  })

  try {
    const hlsPath = await transcoder.transcode()
    console.log('Successfully Transcoded Video')
  } catch (err) {
    console.log(err)
  }
}

transcodeVideo()

Documentation:

Options

When creating a new instance of the Transcoder class, you can supply a third parameter options as an object which will override the default behaviour / settings of hls-transcoder. The possible options and their default values are as follows:

• allowUpscaling
  • Description: When set to false renditions will only be transcoded if the original video is the same resolution or higher than that of the rendition being transcoded. When set to true
  • Default: false
  • Type: boolean | undefined
• ffmpegPath
  • Description: Allows specifying which PATH hls-transcoder should use when invoking an ffmpeg child_process
  • Default: ffmpeg
  • Type: string | undefined
• ffprobePath
  • Description: Allows specifying which PATH hls-transcoder should use when invoking an ffprobe child_process
  • Default: ffprobe
  • Type: string | undefined
• renditions
  • Description: The various resolutions and bitrates hls-transcoder will use when transcoding video files
  • Default: See default renditions
  • Type: RenditionOptions | undefined

Setting event handlers

The Transcoder class extends EventEmitter and will emit the following events:

• 'error'
• 'stderr'
• 'progress'
• 'end'

'error' - transcoding errors

transcoder.on('error', (err) => {
  console.error(err)
})

'stderr' - information ffmpeg sends via the command line

transcoder.on('stderr', (data) => {
  console.log(data)
})

'progress' - transcoding progress information

transcoder.on('progress', (progress) => {
  console.log(progress)
})

The progress event is emitted everytime ffmpeg reports progress information. The progress object contains the following keys:

• frame: total processed frame count
• fps: framerate at which FFmpeg is currenlty processing

'end' - information about ffmpegs exit status

transcoder.on('end', (data) => {
  console.log(data)
})

Ongoing TODOS:

• Progress Bar
• Add option for outputPath param per Rendition
• Add option for Renditions per Resolution
• Fix ffmpeg stderr and stdout processing / parsing
  • Currently in progress
• Test and/or handle .ts file name overflows
  • ie. '1080p_0.ts' where number of ts segments > 10
  • Figured out, default behavior is to just keep adding numbers, ie 11, 12, 13 - so this shouldn't be an issue unless there's a use case where a program is expecting the filenames to match a specfic pattern like that
• Create dir automatically if doesn't exist?
  • Should do this, right now it fails silently if output dir doesn't exist
• Option to enable / disable overwrite?
• Invalid dimensions for renditions appear to fail silently