substract v1.0.1

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.

OCROptions

OutputOptions

Callbacks

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

Callbacks

OcrCallbacks

License

This project is licensed under the MIT License.

Acknowledgements

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