Substract

Substract is a Node.js library designed to extract hard-coded subtitles from videos efficiently. Leveraging powerful tools like FFmpeg, Apple's OCR engine, and parallel processing, Substract provides a seamless way to retrieve subtitles embedded directly within video files.

Table of Contents

• Features
• Installation
• Usage
• API Reference
  • substract
• Options
  • SubstractOptions
• Callbacks
• License

Features

• Efficient Frame Extraction: Extract frames from videos at specified intervals.
• Duplicate Frame Filtering: Remove similar or consecutive duplicate frames to optimize processing.
• OCR Integration: Utilize Apple's OCR engine for accurate text recognition.
• Concurrency Control: Manage the number of concurrent OCR processes to balance performance and resource usage.
• Customizable Options: Tailor the extraction process with various configuration options.
• Comprehensive Callbacks: Hook into different stages of the extraction process for enhanced control and monitoring.
• 100% Test Coverage: Robust unit tests ensure reliability and stability.

Installation

Ensure you have Node.js v20.0.0 or higher installed.

npm install substract

or

pnpm install substract

or

yarn add substract

Usage

Here's a basic example of how to use Substract to extract subtitles from a video:

import { substract } from 'substract';

const videoFile = 'path/to/video.mp4';
const outputFile = 'path/to/output.json';

const options = {
    ocrOptions: {
        appleBinaryPath: '/path/to/ocr/binary', // you can get this from https://github.com/glowinthedark/macOCR
    },
    outputOptions: {
        outputFile,
    },
    callbacks: {
        onGenerateFramesStarted: async (videoFile) => {
            console.log(`Started generating frames for ${videoFile}`);
        },
        onGenerateFramesFinished: async (frames) => {
            console.log(`Finished generating ${frames.length} frames`);
        },
        onOcrFinished: (ocrResults) => {
            console.log('OCR processing completed');
        },
        onOcrProgress: (frame, index) => {
            console.log(`Processing frame ${index + 1}: ${frame.filename}`);
        },
    },
    concurrency: 5, // Optional: Limits the number of concurrent OCR processes
    duplicateTextThreshold: 0.9, // Optional: Threshold for filtering duplicate text
    frameOptions: {
        cropOptions: { top: 10, bottom: 20 }, // Optional: Crop options for frame extraction
        frequency: 5, // Optional: Extract frames every 5 seconds
    },
};

substract(videoFile, options)
    .then((outputPath) => {
        if (outputPath) {
            console.log('OCR results saved to:', outputPath);
        } else {
            console.log('No frames were generated. Aborting subtitle extraction.');
        }
    })
    .catch((error) => {
        console.error('Error extracting subtitles:', error);
    });

API Reference

substract(videoFile, options)

Extracts hard-coded subtitles from a video file.

Parameters

• videoFile: string
  Path to the video file from which to extract subtitles.

• options: SubstractOptions
  Configuration options for the extraction process.

Returns

• Promise<null | string>
  Resolves to the path of the output JSON file containing OCR results if successful, or null if no frames were generated.

Options

SubstractOptions

Configuration options for the substract function.

Property	Type	Description
ocrOptions	OCROptions	Options related to the OCR engine.
outputOptions	OutputOptions	Options related to the output file.
callbacks	Callbacks	Callback functions to hook into various stages of the extraction process.
concurrency	number (optional)	Limits the number of concurrent OCR processes. Default is 5.
duplicateTextThreshold	number (optional)	Threshold for filtering duplicate text. Values range between 0 and 1. Default is undefined.
frameOptions	FrameOptions (optional)	Options for frame extraction, such as cropping and extraction frequency.

OCROptions

Property	Type	Description
appleBinaryPath	string	Path to the Apple OCR binary executable.
callbacks	OcrCallbacks (optional)	Callback functions specific to OCR processing.
concurrency	number (optional)	Number of concurrent OCR processes.

OutputOptions

Property	Type	Description
outputFile	string	Path to save the OCR results in JSON format.

Callbacks

Substract provides several callbacks to monitor and control the extraction process.

Callbacks

Callback	Description
onGenerateFramesStarted	Called when frame generation starts. Receives the video file path.
onGenerateFramesFinished	Called when frame generation finishes. Receives an array of generated frames.
onOcrStarted	Called when OCR processing starts. Receives an array of frames being processed.
onOcrFinished	Called when OCR processing finishes. Receives an array of OCR results.
onOcrProgress	Called after each frame is processed. Receives the frame and its index.

OcrCallbacks

Callback	Description
onOcrFinished	Called when OCR processing finishes. Receives an array of OCR results.
onOcrProgress	Called after each frame is processed. Receives the frame and its index.
onOcrStarted	Called when OCR processing starts. Receives an array of frames.

License

This project is licensed under the MIT License.

Acknowledgements

The Apple OCR method requires the build of the tool from here: macOCR