NodeAV

Appearance

node-av / lib / FFmpegError

Class: FFmpegError ​

Defined in: src/lib/error.ts:140

FFmpeg error handling class.

Provides utilities for handling and converting FFmpeg error codes. FFmpeg uses negative values for errors, with both FFmpeg-specific codes and POSIX error codes converted to negative values. This class provides methods to check, convert, and throw errors based on FFmpeg return codes.

Example ​

typescript
import { FFmpegError } from 'node-av';
import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av/constants';

// Check and throw errors
const ret = await codecContext.sendPacket(packet);
FFmpegError.throwIfError(ret, 'sendPacket');

// Handle specific errors
if (ret === AVERROR_EAGAIN) {
  // Need to receive frames first
} else if (ret === AVERROR_EOF) {
  // End of stream
}

// Get error description
const errorMsg = FFmpegError.strerror(ret);
console.error(`Error: ${errorMsg}`);

See ​

av_strerror - FFmpeg Doxygen

Extends ​

  • Error

Implements ​

Constructors ​

Constructor ​

new FFmpegError(code?): FFmpegError

Defined in: src/lib/error.ts:143

Parameters ​

code? ​

number

Returns ​

FFmpegError

Overrides ​

Error.constructor

Properties ​

cause? ​

optional cause: unknown

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from ​

Error.cause

name ​

name: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.name

stack? ​

optional stack: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from ​

Error.stack

stackTraceLimit ​

static stackTraceLimit: number

Defined in: node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from ​

Error.stackTraceLimit

Accessors ​

code ​

Get Signature ​

get code(): number

Defined in: src/lib/error.ts:314

Error code.

The FFmpeg error code (negative value).

Returns ​

number

message ​

Get Signature ​

get message(): string

Defined in: src/lib/error.ts:323

Error message.

Human-readable description of the error.

Returns ​

string

Overrides ​

Error.message

Methods ​

getNative() ​

getNative(): NativeFFmpegError

Defined in: src/lib/error.ts:334

Internal

Get the underlying native FFmpegError object.

Returns ​

NativeFFmpegError

The native FFmpegError binding object

Implementation of ​

NativeWrapper.getNative

AVERROR() ​

static AVERROR(errorName): AVError

Defined in: src/lib/error.ts:199

Convert POSIX error name to FFmpeg error code.

Converts platform-specific POSIX error to FFmpeg's negative error code.

Direct mapping to AVERROR() macro.

Parameters ​

errorName ​

PosixError

POSIX error name

Returns ​

AVError

FFmpeg error code

Example ​

typescript
import { PosixError } from 'node-av';

const code = FFmpegError.AVERROR(PosixError.ENOMEM);
// Returns platform-specific negative error code

See ​

PosixError For available error names

captureStackTrace() ​

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters ​

targetObject ​

object

constructorOpt? ​

Function

Returns ​

void

Inherited from ​

Error.captureStackTrace

fromCode() ​

static fromCode(code): null | FFmpegError

Defined in: src/lib/error.ts:244

Create error from code.

Creates an FFmpegError instance if the code is an error.

Parameters ​

code ​

number

FFmpeg return code

Returns ​

null | FFmpegError

Error instance or null if not an error

Example ​

typescript
const error = FFmpegError.fromCode(ret);
if (error) {
  console.error(`Error: ${error.message}`);
}

is() ​

static is(code, errorCode): boolean

Defined in: src/lib/error.ts:305

Check if code matches specific error.

Convenience method to check for specific error codes.

Parameters ​

code ​

number

Return code to check

errorCode ​

number

Error code to compare against

Returns ​

boolean

True if codes match

Example ​

typescript
import { AVERROR_EOF } from 'node-av/constants';

if (FFmpegError.is(ret, AVERROR_EOF)) {
  console.log('End of file reached');
}

isError() ​

static isError(error): error is Error

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​

error ​

unknown

Returns ​

error is Error

Inherited from ​

Error.isError

isFFmpegError() ​

static isFFmpegError(code): boolean

Defined in: src/lib/error.ts:220

Check if a code is an FFmpeg error.

FFmpeg errors are negative values.

Parameters ​

code ​

number

Return code to check

Returns ​

boolean

True if code is an error

Example ​

typescript
const ret = await formatContext.readFrame(packet);
if (FFmpegError.isFFmpegError(ret)) {
  console.error('Read failed');
}

prepareStackTrace() ​

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:56

Parameters ​

err ​

Error

stackTraces ​

CallSite[]

Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

Error.prepareStackTrace

strerror() ​

static strerror(errnum): string

Defined in: src/lib/error.ts:174

Get human-readable error message for code.

Converts an FFmpeg error code to a descriptive string.

Direct mapping to av_strerror().

Parameters ​

errnum ​

number

FFmpeg error code

Returns ​

string

Error description string

Example ​

typescript
const message = FFmpegError.strerror(-22);
console.log(message); // "Invalid argument"

throwIfError() ​

static throwIfError(code, operation?): void

Defined in: src/lib/error.ts:275

Throw if code indicates an error.

Checks if the code is an error and throws an FFmpegError if so. Commonly used pattern for FFmpeg API calls.

Parameters ​

code ​

number

FFmpeg return code

operation? ​

string

Optional operation name for context

Returns ​

void

Throws ​

If code is negative

Example ​

typescript
// Simple error check
const ret = codecContext.open(codec);
FFmpegError.throwIfError(ret);

// With operation context
const ret2 = await formatContext.writeHeader();
FFmpegError.throwIfError(ret2, 'writeHeader');
// Throws: "writeHeader failed: [error message]"