From b277631f38f207333ac64688823db1bac8e1065a Mon Sep 17 00:00:00 2001
From: Jerome Wu <jeromewus@gmail.com>
Date: Mon, 24 Jul 2023 22:08:15 +0800
Subject: [PATCH] Update docs and types

---
 packages/ffmpeg/src/classes.ts  |  4 +--
 packages/ffmpeg/src/types.ts    |  2 +-
 packages/types/types/index.d.ts | 45 ++++++++++++++++++++++++++++++++-
 src/bind/ffmpeg/bind.js         |  4 +--
 src/fftools/ffmpeg.c            |  4 +--
 5 files changed, 51 insertions(+), 8 deletions(-)

diff --git a/packages/ffmpeg/src/classes.ts b/packages/ffmpeg/src/classes.ts
index a055d0a..291b67e 100644
--- a/packages/ffmpeg/src/classes.ts
+++ b/packages/ffmpeg/src/classes.ts
@@ -104,7 +104,7 @@ export class FFmpeg {
    *
    * @example
    * ```ts
-   * ffmpeg.on(FFmpeg.LOG, ({ message }) => {
+   * ffmpeg.on("log", ({ type, message }) => {
    *   // ...
    * })
    * ```
@@ -114,7 +114,7 @@ export class FFmpeg {
    *
    * @example
    * ```ts
-   * ffmpeg.on(FFmpeg.PROGRESS, ({ progress }) => {
+   * ffmpeg.on("progress", ({ progress, time }) => {
    *   // ...
    * })
    * ```
diff --git a/packages/ffmpeg/src/types.ts b/packages/ffmpeg/src/types.ts
index 3618901..7f77e54 100644
--- a/packages/ffmpeg/src/types.ts
+++ b/packages/ffmpeg/src/types.ts
@@ -119,7 +119,7 @@ export interface LogEvent {
 
 export interface ProgressEvent {
   progress: number;
-  elapsed: number;
+  time: number;
 }
 
 export type ExitCode = number;
diff --git a/packages/types/types/index.d.ts b/packages/types/types/index.d.ts
index 9cd8570..368615f 100644
--- a/packages/types/types/index.d.ts
+++ b/packages/types/types/index.d.ts
@@ -6,10 +6,23 @@ export type StringPointer = Pointer;
 export type StringArrayPointer = Pointer;
 export type DateString = string;
 
+/**
+ * Options for readFile.
+ *
+ * @see [Emscripten File System API](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.readFile)
+ * @category File System
+ */
 export interface ReadFileOptions {
+  /** encoding of the file, must be `binary` or `utf8` */
   encdoing: string;
 }
 
+/**
+ * Describes attributes of a node. (a.k.a file, directory)
+ *
+ * @see [Emscripten File System API](https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.stat)
+ * @category File System
+ */
 export interface Stat {
   dev: number;
   ino: number;
@@ -26,6 +39,12 @@ export interface Stat {
   blocks: number;
 }
 
+/**
+ * Functions to interact with Emscripten FS library.
+ *
+ * @see [Emscripten File System API](https://emscripten.org/docs/api_reference/Filesystem-API.html)
+ * @category File System
+ */
 export interface FS {
   mkdir: (path: string) => void;
   rmdir: (path: string) => void;
@@ -35,21 +54,42 @@ export interface FS {
   readdir: (path: string) => string[];
   unlink: (path: string) => void;
   stat: (path: string) => Stat;
+  /** mode is a numeric notation of permission, @see [Numeric Notation](https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation) */
   isFile: (mode: number) => boolean;
+  /** mode is a numeric notation of permission, @see [Numeric Notation](https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation) */
   isDir: (mode: number) => boolean;
 }
 
+/**
+ * Arguments passed to setLogger callback function.
+ */
 export interface Log {
+  /** file descriptor of the log, must be `stdout` or `stderr` */
   type: string;
   message: string;
 }
 
+/**
+ * Arguments passed to setProgress callback function.
+ */
+export interface Progress {
+  /** progress of the operation, interval = [0, 1] */
+  progress: number;
+  /** time of transcoded media in microseconds, ex: if a video is 10 seconds long, when time is 1000000 means 1 second of the video is transcoded already. */
+  time: number;
+}
+
+/**
+ * FFmpeg core module, an object to interact with ffmpeg.
+ */
 export interface FFmpegCoreModule {
+  /** default arguments prepend when running exec() */
   DEFAULT_ARGS: string[];
   FS: FS;
   NULL: Pointer;
   SIZE_I32: number;
 
+  /** return code of the ffmpeg exec, error when ret != 0 */
   ret: number;
   timeout: number;
   mainScriptUrlOrBlob: string;
@@ -58,11 +98,14 @@ export interface FFmpegCoreModule {
   reset: () => void;
   setLogger: (logger: (log: Log) => void) => void;
   setTimeout: (timeout: number) => void;
-  setProgress: (handler: (progress: number, elapsed: number) => void) => void;
+  setProgress: (handler: (progress: Progress) => void) => void;
 
   locateFile: (path: string, prefix: string) => string;
 }
 
+/**
+ * Factory of FFmpegCoreModule.
+ */
 export type FFmpegCoreModuleFactory = (
   moduleOverrides?: Partial<FFmpegCoreModule>
 ) => Promise<FFmpegCoreModule>;
diff --git a/src/bind/ffmpeg/bind.js b/src/bind/ffmpeg/bind.js
index b512b5b..bf85751 100644
--- a/src/bind/ffmpeg/bind.js
+++ b/src/bind/ffmpeg/bind.js
@@ -74,8 +74,8 @@ function setProgress(handler) {
   Module["progress"] = handler;
 }
 
-function receiveProgress(progress, elapsed) {
-  Module["progress"]({ progress, elapsed });
+function receiveProgress(progress, time) {
+  Module["progress"]({ progress, time });
 }
 
 function reset() {
diff --git a/src/fftools/ffmpeg.c b/src/fftools/ffmpeg.c
index e4f3ff8..cc0884c 100644
--- a/src/fftools/ffmpeg.c
+++ b/src/fftools/ffmpeg.c
@@ -1505,8 +1505,8 @@ static void print_final_stats(int64_t total_size)
     }
 }
 
-EM_JS(void, send_progress, (double progress, double elapsed), {
-    Module.receiveProgress(progress, elapsed);
+EM_JS(void, send_progress, (double progress, double time), {
+    Module.receiveProgress(progress, time);
 });
 
 static void print_report(int is_last_report, int64_t timer_start, int64_t cur_time)