← Home
Core Concepts

Progress Tracking

The Progress Tracking system allows you to monitor job execution, observe pipelines, and react to lifecycle events for long-running media tasks.

Core Concepts

EventEmitter-Based

Progress is tracked via events for real-time updates

Granular Tracking

Progress is emitted per job and per pipeline

Consistent Contract

Progress payload follows a standardized structure

ProgressInfo Interface

Progress payload follows a consistent structure:

progress-info.ts
1
2
3
4
5
6
7
typescript
percent:number0–100 completion percentage
frames?:numbercurrent processed frames (if applicable)
currentFps?:numberreal-time processing speed
eta?:numberestimated time remaining (seconds)
time?:stringcurrent processed timestamp (HH:MM:SS)

Tracking Job Progress

Each Job instance exposes an event emitter for progress and completion monitoring:

job-progress-tracking.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
typescript

Job Events

startnoneJob started execution
progressProgressInfoProgress update with percent + metrics
complete{ outputPath }Job finished successfully
errorErrorJob failed

Tracking Pipeline Progress

Pipelines aggregate multiple jobs and allow global monitoring:

pipeline-progress-tracking.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
typescript

Pipeline Events

progressProgressInfoAggregated progress across all jobs
completenoneAll jobs completed successfully
errorErrorOne or more jobs in pipeline failed

Real-time Progress Example

Live Progress Updates

Job started
Progress: 15.2% | Frames: 456 | FPS: 24.1 | ETA: 45s
Progress: 32.8% | Frames: 984 | FPS: 26.3 | ETA: 28s
Progress: 67.5% | Frames: 2025 | FPS: 25.8 | ETA: 12s
Progress: 94.1% | Frames: 2823 | FPS: 24.9 | ETA: 2s
Job finished: output.mp4

Best Practices

Always Attach Error Listeners

Avoid uncaught promise rejections by handling all error events

Use Appropriate Progress Data

Use progress.percent for UI bars; eta for time estimation

Pipeline-Level Tracking

For multi-step pipelines, use pipeline progress over manual aggregation

Consider Granularity

Jobs emit granular progress; pipelines emit aggregated progress

Key Guidelines:

  • Always attach error listeners to avoid uncaught promise rejections
  • Use progress.percent for UI progress bars; eta for time estimation
  • For multi-step pipelines, consider using pipeline-level progress rather than manual aggregation
  • Jobs emit more granular progress; pipelines emit aggregated progress

Advanced Progress Handling

advanced-progress.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
typescript

Master Error Handling Next

Now that you can track progress effectively, learn how to handle errors gracefully and build robust media processing applications with MediaX.

Learn Error HandlingView Progress Examples
[3]