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