Skip to main content

​
Job Status Details

​
DETECTED

  • What it means: File found during library scan
  • User action: None (automatic)
  • Duration: Milliseconds
  • Next step: Health check runs automatically

​
HEALTH_CHECK

  • What it means: BitBonsai is validating file integrity with FFmpeg
  • Checks performed:
    • File exists and is readable
    • Container format is valid (MP4, MKV, AVI, etc.)
    • Video/audio streams are decodable
    • Duration and metadata are accessible
    • No critical corruption in file structure
  • User action: None (automatic)
  • Duration: 1-5 seconds per file
  • Next step:
    • Healthy files → NEEDS_DECISION
    • Corrupted files → CORRUPTED (hourly auto-requeue for re-validation)
Health checks prevent encoding failures by detecting corrupt files before wasting CPU time. Failed health checks are logged with detailed error messages.

​
NEEDS_DECISION

  • What it means: File is healthy and ready to encode
  • User action: Select codec (HEVC/AV1) and click “Queue Selected”
  • Where to find: Encoding tab → filter by NEEDS_DECISION
  • Filters available:
    • Codec (find H.264 videos to upgrade)
    • Resolution (1080p, 4K, etc.)
    • Bitrate (target high-bitrate files)
    • File size (prioritize large files)

​
QUEUED

  • What it means: Job is waiting for an available worker node
  • User action: None (automatic)
  • Duration: Seconds to minutes (depends on queue depth)
  • Priority: First-in, first-out (FIFO)
  • Next step: Starts encoding when worker is free
Queue depth is visible in the Encoding tab header: “3 queued, 2 encoding”. Add more worker nodes to process queued jobs faster.

​
TRANSFERRING

  • What it means: (Multi-node only) NFS sync is in progress before encoding begins
  • User action: None (automatic)
  • Duration: Usually seconds; longer if NFS mount is slow or recovering
  • Why this happens: The worker node is confirming the source file is accessible via the shared NFS mount before starting FFmpeg. This is a brief sync check, not a file copy.
  • Next step: Encoding starts immediately after the file is confirmed accessible
If jobs stay in TRANSFERRING for more than 30 seconds, your NFS mount may be degraded. Check NFS connectivity on all nodes. See Multi-Node Setup for NFS configuration requirements — shared storage is mandatory for multi-node encoding.

​
ENCODING

  • What it means: FFmpeg is actively encoding the video
  • User action: Monitor progress, or pause/cancel if needed
  • Duration: Minutes to hours (depends on codec, resolution, and hardware acceleration)
  • What you see:
    • Progress percentage (0-100%)
    • Estimated time remaining
    • Encoding speed (FPS)
    • Output file size estimate
    • Current vs. target bitrate

​
Progress Bar Breakdown

[████████████░░░░░░░░░░░░] 45% - 12:34 remaining
 │           │             │    └─ ETA based on current speed
 │           │             └─ Percentage complete
 │           └─ Empty portion (not yet encoded)
 └─ Filled portion (encoded)

​
Encoding Speed (FPS)

SpeedHardwareCodecNotes
5-15 FPSCPU (Intel i5)HEVCTypical for 1080p movies
20-40 FPSCPU (Intel i7/i9)HEVCFast encoding
40-80 FPSGPU (NVIDIA GTX 1660+)HEVCHardware acceleration
1-5 FPSCPUAV1Very slow but best quality
Slow encoding? Check Settings → Hardware Acceleration and enable NVIDIA/Intel/AMD GPU encoding if available. HEVC on GPU is 3-10x faster than CPU.

​
PAUSED

  • What it means: User manually paused encoding
  • User action: Click Resume to continue
  • Duration: Indefinite (until user resumes)
  • Progress saved: Yes, resumes from exact frame
  • Use case: Free up CPU/GPU for other tasks temporarily

​
VERIFYING

  • What it means: Encoded file is being validated for corruption
  • Checks performed:
    • Output file exists and is readable
    • FFprobe can parse container and streams
    • Duration matches original (within 2 seconds)
    • Video/audio streams are decodable
  • User action: None (automatic)
  • Duration: 1-3 seconds
  • Next step:
    • Healthy output → COMPLETED
    • Corrupted output → CORRUPTED (hourly auto-requeue for re-validation)
If verification fails repeatedly (3+ retries), the source file may be corrupted. Check the original file with ffprobe or VLC for playback issues.

​
COMPLETED

  • What it means: Encoding succeeded and file replaced
  • User action: None (automatic)
  • What happened:
    1. Original file backed up to /media/.bitbonsai/originals/[library]/[file]
    2. Encoded file replaces original in library
    3. Library metadata updated (new codec, bitrate, file size)
    4. Job marked complete and removed from active queue
  • File location: Same path as original (in-place replacement)
  • Backup location: [library-path]/.bitbonsai/originals/[relative-path]

​
File Size Comparison

Typical savings after encoding:
Original CodecTarget CodecFile Size Reduction
H.264 (1080p)HEVC40-50% smaller
H.264 (1080p)AV150-60% smaller
H.264 (4K)HEVC50-60% smaller
H.264 (4K)AV160-70% smaller
Example: A 10 GB H.264 movie encoded to HEVC becomes ~5 GB (50% savings). No quality loss with default CRF settings.

​
FAILED

  • What it means: Encoding encountered an error
  • User action:
    • Check error message in job details
    • Click Retry to manually retry
    • Auto-retries 3x before stopping
  • Common causes:
    • Corrupted source file (skip it)
    • Insufficient disk space (free up space)
    • FFmpeg crash (bug in codec)
    • Hardware encoder failure (try CPU fallback)
  • Auto-retry behavior:
    • 1st retry: Immediate
    • 2nd retry: 5 minutes later
    • 3rd retry: 15 minutes later
    • After 3 failures: Stops, requires manual retry

​
Error Categories

Error TypeCauseFix
Source CorruptedOriginal file unreadableSkip file or re-download
Disk FullNo space for output fileFree up space, job auto-retries
Codec ErrorFFmpeg crash or unsupported streamTry different codec (HEVC → AV1)
Hardware FailureGPU encoder crashDisable hardware acceleration in Settings
Permission DeniedDocker volume permissionsFix with chmod -R 777 /media
  1. Go to Encoding tab
  2. Filter by Failed status
  3. Click job row to expand details
  4. Error message shows FFmpeg output with:
    • Error category
    • Root cause analysis
    • Suggested fix
    • Full FFmpeg stderr log
Example error:
Error Category: SOURCE_CORRUPTED
Message: Invalid data found when processing input
Suggestion: Source file may be corrupted. Try re-downloading or skip this file.
FFmpeg stderr: [mov,mp4,m4a,3gp,3g2,mj2 @ 0x...] moov atom not found

​
CANCELLED

  • What it means: User manually cancelled encoding
  • User action: Job is removed from queue
  • Progress lost: Yes, cannot resume cancelled jobs
  • Use case: Queued wrong file or changed mind about codec

​
Job Details Panel

Click any job in the Encoding tab to view detailed information:
FieldDescription
Source FileFull file path in library
Target CodecHEVC (H.265), AV1, or VP9
ProgressPercentage complete (0-100%)
SpeedEncoding speed in FPS
Time RemainingETA based on current speed
Original SizeFile size before encoding
Output SizeEstimated file size after encoding
Original CodecSource codec (usually H.264)
ResolutionVideo resolution (1080p, 4K, etc.)
Original BitrateSource video bitrate (Mbps)
Target BitrateOutput video bitrate (Mbps)
Worker NodeWhich node is processing this job
Started AtWhen encoding began
Error Message(FAILED jobs only) FFmpeg error details
Pro tip: Sort jobs by “Time Remaining” to see which jobs finish soonest. Large 4K movies may take hours, while 1080p TV episodes finish in 5-10 minutes.