Skip to main content
This guide walks you through creating your first library, scanning for videos, and queuing encoding jobs.

​
Prerequisites

  • BitBonsai backend running with access to video files
  • Docker volume mounts configured for video directories (see Configuration)
  • At least one worker node connected (main node or linked nodes)
1

Open the Libraries page

Click Libraries in the left sidebar navigation.The Libraries page displays all configured libraries and their encoding statistics.
2

Click Add Library button

Click the Add Library button in the top-right corner of the page.A dialog will appear with library configuration fields.

​
Configure Library Settings

1

Enter library name

Provide a descriptive name for your library (e.g., “Movies”, “TV Shows”, “Documentaries”).
Name: Movies
2

Specify library path

Enter the absolute path inside the Docker container where your videos are mounted.
Path: /videos/movies
The path must match your Docker volume mount. If you mounted /mnt/media/movies to /videos/movies in docker-compose.yml, use /videos/movies here.
For Unraid setups, common paths are:
  • /videos/movies (mapped from /mnt/user/media/movies)
  • /videos/tv (mapped from /mnt/user/media/tv)
3

Select target codec

Choose the encoding codec for this library:
CodecCompressionSpeedQualityUse Case
HEVC (H.265)HighFastExcellentGeneral purpose, wide device support
AV1HigherSlowerSuperiorMaximum compression, modern devices
HEVC is recommended for most users. AV1 provides better compression but encodes slower and requires newer hardware for playback.
4

Save the library

Click Save to create the library.The library appears in the Libraries list with 0 videos scanned.

​
Scan for Videos

1

Start the scan

Click the Scan button (magnifying glass icon) next to your newly created library.BitBonsai will recursively search the library path for video files.
Scanning large libraries (1000+ files) may take 1-5 minutes. The UI updates automatically when complete.
2

Review detected videos

Once scanning completes, click the library name to view detected videos.The video table displays:
ColumnDescription
FilenameVideo file name and relative path
SizeFile size in GB
CodecCurrent video codec (H.264, HEVC, etc.)
DurationVideo length in HH:MM:SS
StatusEncoding status (NOT_QUEUED, QUEUED, ENCODING, COMPLETE)
Videos already encoded in the target codec are marked SKIPPED and cannot be re-encoded (to prevent quality loss from transcoding already-compressed files).

​
Queue Videos for Encoding

1

Select videos to encode

Use checkboxes to select specific videos, or click Select All to choose all eligible videos.
Only videos with status NOT_QUEUED can be selected. Videos already in queue or encoded are disabled.
2

Queue selected videos

Click the Queue Selected button at the top of the video table.Selected videos change from NOT_QUEUED → QUEUED status.
3

Alternative: Queue all videos

To queue all eligible videos at once, click Queue All instead of selecting individually.This is useful for initial library setup when you want to encode everything.

​
Monitor Encoding Progress

1

Navigate to Jobs page

Click Jobs in the left sidebar to view all encoding jobs.Jobs appear in the queue with status progression:
QUEUED → ENCODING → COMPLETE
2

Track job progress

The Jobs page displays:
  • Current progress (percentage, frames processed)
  • Encoding speed (fps)
  • Estimated time remaining (ETA)
  • Worker node handling the job
  • File size change (original → encoded)
For detailed job monitoring and troubleshooting, see Understanding Jobs.

​
What Happens Next?

Once videos are queued, BitBonsai automatically:
  1. Distributes jobs to available worker nodes based on load
  2. Encodes videos using FFmpeg with optimized quality settings
  3. Validates output to ensure no corruption or quality loss
  4. Replaces original with encoded version (if configured)
  5. Moves to next job in queue

Next Steps

Learn how to monitor job progress, handle failures, and optimize encoding performance.

​
Common Issues

Causes:
  • Path doesn’t exist inside Docker container
  • Volume mount misconfigured in docker-compose.yml
  • Files are not recognized video formats (MP4, MKV, AVI, MOV)
Solution:
  • Verify path exists: docker exec bitbonsai-backend ls /videos/movies
  • Check docker-compose.yml volume mounts
  • Ensure files have video extensions
Cause: Videos are already encoded in the target codec (e.g., library set to HEVC, but videos are already H.265).Solution:
  • This is intentional to prevent quality loss from re-encoding
  • If you want to re-encode, delete the library and create a new one with a different codec
Causes:
  • No videos selected
  • Selected videos already queued or encoded
  • No worker nodes available
Solution:
  • Select videos with NOT_QUEUED status
  • Check worker node health in Settings → Nodes
Causes:
  • No worker nodes connected
  • All workers at max concurrent job capacity
  • Worker nodes offline or unhealthy
Solution:
  • Check worker node status: Settings → Nodes
  • Verify main/child node services running
  • Review worker logs: docker logs bitbonsai-backend

​
Tips for Large Libraries

For libraries with 500+ videos:
  • Queue videos in batches (e.g., 50-100 at a time) to monitor progress
  • Start with smallest files to verify settings before encoding large videos
  • Use multiple linked nodes to parallelize encoding across hardware
  • Enable auto-replace to automatically delete originals after successful encoding
Always backup your original files before enabling auto-replace. While BitBonsai validates encoded output, hardware failures or power loss during replacement can cause data loss.