Progress and sessions

The first native progress callback is 0 after input preparation. Intermediate callbacks depend on progressInterval and export duration; there may not be an event for every percentage point. Progress reaches 1 only after the completed output is published. It is not an upload measure or time estimate. Exceptions thrown by progress callbacks are ignored, including batch callbacks.

The top-level compress() and cancelCompress() share one session. A new native compression request replaces, cancels, and rejects that session's previous request, even when the new input later fails to open. JavaScript input/option validation happens first: those validation errors leave the active export running. Calls are replaced, not queued.

cancelCompress(): Promise<void> cancels the shared default session. Cancelling while idle succeeds. The original compression promise rejects separately; attach its error handler when starting the operation. Cancelling does not delete completed files. Ordinary cancellation has no guaranteed error name or stable cross-platform native error-code enum.

Independent work

createVideoCompressor(): VideoCompressor returns compress(inputUri, options?, onProgress?): Promise<string> and cancel(): Promise<void>. Each instance has independent cancellation state. Each hook and batch also owns a separate session.

The following helper attaches an error handler immediately and returns a cancel action. The result union belongs to the example, not to the library API.

import { createVideoCompressor } from "react-native-media-transformer";

export function beginCompression(inputUri: string) {
  const session = createVideoCompressor();
  const result = session.compress(inputUri, { quality: "medium" }).then(
    (path) => ({ ok: true as const, path }),
    (error: unknown) => ({
      ok: false as const,
      error: error instanceof Error ? error : new Error(String(error)),
    }),
  );

  return { result, cancel: () => session.cancel() };
}

Call beginCompression(uri) from your start action, keep the returned object, and await its result. Call its cancel() from your cancel action, handling cancellation-call rejections too.

Independent sessions may run concurrently if the device has sufficient codec resources. They all share the media-transformer cache directory: use unique filenames across sessions. With overwrite enabled, a later successful export to the same destination replaces the earlier completed file. Use batches for sequential work. Metadata and thumbnails are independent of compression and are not stopped by cancelCompress() or a compressor's cancel().