Skip to main content

​
General Questions

BitBonsai supports all video formats that FFmpeg can decode, including:
  • MP4 (.mp4, .m4v)
  • Matroska (.mkv)
  • AVI (.avi)
  • QuickTime (.mov)
  • WebM (.webm)
  • MPEG (.mpg, .mpeg)
  • FLV (.flv)
  • WMV (.wmv)
The app automatically detects codec compatibility. If a file is already in HEVC or AV1, it’s skipped unless you force re-encoding.See Understanding Jobs for more details on job statuses.
Storage savings depend on the source codec and target codec:
Source → TargetTypical Savings
H.264 → HEVC40-50%
H.264 → AV150-70%
MPEG-2 → HEVC60-80%
Example:
  • 1 TB of H.264 movies → ~500 GB as HEVC
  • 1 TB of H.264 movies → ~350 GB as AV1
Actual savings vary based on:
  • Source quality (bitrate, resolution)
  • CRF/quality setting (lower CRF = larger files)
  • Content type (animation compresses better than live action)
High-quality 4K files may save less (30-40%) due to already efficient encoding.
Yes. BitBonsai supports hardware acceleration via FFmpeg:
VendorTechnologyLinuxWindows
NVIDIANVENC✅✅
IntelQuick Sync (QSV)✅✅
AMDAMF/VCE✅✅
Configuration: Hardware encoding is configured per-library. When creating or editing a library, select the encoder:
Codec: HEVC
Encoder: NVIDIA NVENC (hevc_nvenc)
Requirements:
  • NVIDIA: GPU with NVENC support + drivers
  • Intel: iGPU with Quick Sync + drivers
  • AMD: GPU with VCE support + drivers
Performance:
  • NVENC: 3-10x faster than CPU encoding
  • Quality: Slightly lower than CPU at same bitrate (acceptable for most users)
See Codec Selection for encoder comparisons.
Yes. BitBonsai has a TRUE RESUME feature that preserves partial encoding progress.How It Works:
  1. Click Pause on an encoding job
  2. Job status changes to PAUSED
  3. FFmpeg process is killed gracefully
  4. Temp file (*.bbtmp) is kept on disk
  5. Click Resume to continue from last keyframe
Benefits:
  • No wasted work (unlike traditional pause which discards progress)
  • Safe to pause/resume anytime
  • Temp files cleaned up automatically on completion
Technical Details:
  • Resume point determined by temp file size vs. expected output
  • If temp file is corrupted, job auto-retries from scratch
  • If temp file is missing (deleted manually), job resets to QUEUED
Limitations:
  • Resume accuracy ~95-98% (may re-encode last 1-2 seconds)
  • Two-pass encoding does not support resume (restarts pass)
BitBonsai has automatic retry and error recovery:Auto-Retry Mechanism:
  1. Job fails (FFmpeg error, disk full, etc.)
  2. Status → QUEUED with retry counter incremented
  3. System retries up to 3 times
  4. After 3 failures → status changes to FAILED
Failed Job Recovery:
  • Review error logs in the job details panel
  • Fix underlying issue (disk space, permissions, corrupted source)
  • Click Retry to manually reset the job
Common Failure Causes:
ErrorCauseSolution
FFmpeg error code 1Corrupted source fileRe-download or remux file
Disk fullInsufficient temp spaceFree up disk space
Permission deniedFile/folder permissionsCheck ownership and rwx permissions
TimeoutJob exceeded max durationIncrease timeout in settings
Auto-Healing:
  • Orphaned jobs (stuck in ENCODING after restart) → auto-reset to QUEUED
  • Corrupted temp files → auto-deleted and job re-queued
  • Health check failures → auto-retry every hour
See Troubleshooting for detailed error diagnostics.

​
Multi-Node & Scaling

BitBonsai supports multi-node distributed encoding. Steps:1. Set Up Main Node (Database Owner)
docker run -d \
  -e ROLE=main \
  -e DATABASE_URL=postgresql://user:pass@localhost:5432/bitbonsai \
  -p 3100:3100 \
  bitbonsai/backend
2. Set Up Child Nodes (Workers)
docker run -d \
  -e ROLE=linked \
  -e MAIN_NODE_URL=http://192.168.1.100:3100 \
  -v /mnt/shared:/media \
  bitbonsai/backend
3. Configure Shared Storage (NFS)
  • All nodes must access the same media files via NFS
  • Recommended: 1 Gbps+ network, NFS v4
  • Mount paths must be identical across nodes
4. Verify Registration
  • Child nodes auto-register with main node on startup
  • Check Settings → Nodes to see all active workers
Architecture:
  • Main node: Owns PostgreSQL, API, job queue
  • Child nodes: Workers only, proxy API calls to main
  • Job distribution: Automatic load balancing via queue system
See Multi-Node Setup for detailed configuration.
Yes. Multi-node support requires a paid license:
TierMax NodesMax Concurrent JobsPrice
FREE1 node1 jobFree
SUPPORTER3 nodes5 jobs$5/month
PROUnlimitedUnlimited$15/month
Features Locked Behind License:
  • Multi-node worker registration
  • Concurrent job execution (>1 job at once)
  • Priority support
How to Purchase:
  1. Visit bitbonsai.io/pricing
  2. Subscribe via Stripe or Patreon
  3. Receive license key via email
  4. Enter key in Settings → License
Trial Period:
  • 14-day free trial for SUPPORTER/PRO tiers
  • No credit card required for FREE tier
  • Downgrade anytime (keeps data)
Why Paid?
  • Server costs (license validation, updates)
  • Development funding (full-time maintainer)
  • Community support (Discord, GitHub)
See Pricing Page for current rates.

​
Video Quality & Codecs

Yes. BitBonsai fully supports 4K and HDR encoding.HDR Metadata Preservation:
  • HDR10 (PQ/ST.2084) → ✅ Preserved
  • HDR10+ → ✅ Preserved (HEVC only)
  • Dolby Vision → ⚠️ Converted to HDR10 (AV1/HEVC)
  • HLG (Hybrid Log-Gamma) → ✅ Preserved
Codec Support:
Codec4KHDR10HDR10+Dolby Vision
HEVC✅✅✅Profile 5 only
AV1✅✅❌❌
Configuration: When encoding HDR content, use:
  • CRF 18-22 (lower = higher quality)
  • Preset: slow (better compression)
  • Color space: Auto-detected from source
Example FFmpeg Command (Auto-Generated):
ffmpeg -i input.mkv \
  -c:v libx265 \
  -crf 20 -preset slow \
  -color_primaries bt2020 \
  -color_trc smpte2084 \
  -colorspace bt2020nc \
  -x265-params "hdr-opt=1:repeat-headers=1" \
  output.mkv
Playback Compatibility:
  • Ensure media player supports HDR (VLC, Plex, Jellyfin)
  • HDR displays required for proper viewing
  • SDR tone-mapping handled by player
See Codec Selection for quality settings.
Both are modern video codecs. Key differences:
FeatureHEVC (H.265)AV1
Compression40-50% better than H.26450-70% better than H.264
Encoding SpeedFast (HW accelerated)Slow (CPU only)
Hardware SupportWide (2015+ devices)Limited (2020+ devices)
LicensingPaid (patent-encumbered)Free (royalty-free)
QualityExcellentSlightly better
When to Use HEVC:
  • Need fast encoding (NVENC, QSV)
  • Wide device compatibility (TVs, phones)
  • Hardware decoding available
When to Use AV1:
  • Maximum compression (archival)
  • Don’t care about encoding time
  • Modern playback devices only
Encoding Time Comparison (1080p movie):
  • H.264 CPU: 1 hour
  • HEVC CPU: 2 hours
  • HEVC NVENC: 15 minutes
  • AV1 CPU: 6 hours
Recommendation:
  • Most users: HEVC with hardware encoding
  • Archival/storage priority: AV1 (set and forget)
  • Compatibility priority: Stick with H.264
See Codec Selection for detailed comparison.

​
Backup & Maintenance

BitBonsai uses PostgreSQL. Backup methods:1. PostgreSQL Dump (Recommended)
# Full backup
docker exec bitbonsai-postgres pg_dump -U bitbonsai > backup.sql

# Restore
docker exec -i bitbonsai-postgres psql -U bitbonsai < backup.sql
2. Volume Backup (Docker)
# Stop containers
docker-compose down

# Backup data volume
tar -czf bitbonsai-data.tar.gz /var/lib/docker/volumes/bitbonsai_postgres_data

# Restore
tar -xzf bitbonsai-data.tar.gz -C /
docker-compose up -d
3. Automated Backups (Cron)
# Add to crontab (daily at 2 AM)
0 2 * * * docker exec bitbonsai-postgres pg_dump -U bitbonsai | gzip > /backups/bitbonsai-$(date +\%Y\%m\%d).sql.gz
What Gets Backed Up:
  • Libraries and scan history
  • Job queue and encoding history
  • Settings and node configuration
  • User preferences
What Doesn’t Get Backed Up:
  • Media files (backup separately via rsync/Duplicati)
  • Temp files (*.bbtmp) - safe to delete
  • Logs (ephemeral, rotate after 30 days)
Restore Testing: Test your backups monthly to ensure they’re valid.
Yes, but WSL2 is required for optimal performance.Option 1: WSL2 + Docker (Recommended)
# Install WSL2
wsl --install

# Install Docker Desktop (with WSL2 backend)
# Download from: https://docker.com/desktop

# Run BitBonsai
docker-compose up -d
Option 2: Native Windows (Not Recommended)
  • NestJS backend runs on Windows
  • FFmpeg works but slower (no native POSIX)
  • NFS shares not supported (use SMB)
  • Path handling issues (backslashes vs. forward slashes)
Why WSL2?
  • Native Linux performance
  • Better FFmpeg efficiency
  • NFS support for multi-node
  • Easier troubleshooting (Docker Compose)
Configuration:
  • Mount media via WSL2: \\wsl$\Ubuntu\mnt\media
  • Database in WSL2 volume (better I/O)
  • Frontend accessible via localhost:4200
Known Limitations:
  • GPU passthrough (NVENC) requires WSL2 + CUDA drivers
  • Network performance slightly lower than bare metal
  • File watchers may lag on large libraries (10K+ files)
See Installation Requirements for system specs.

​
Network & Remote Access

BitBonsai provides multiple monitoring options:1. Web UI (Mobile-Friendly)
Access: http://YOUR_IP:4200
Features:
- Real-time job progress (%)
- Live FFmpeg output logs
- Queue status and ETA
- Responsive design (works on phones)
2. API Endpoints
# Get all jobs
curl http://YOUR_IP:3100/api/jobs

# Get specific job
curl http://YOUR_IP:3100/api/jobs/123

# Get encoding stats
curl http://YOUR_IP:3100/api/statistics
3. WebSocket (Real-Time Updates)
// Connect to WebSocket
const ws = new WebSocket('ws://YOUR_IP:3100');

ws.onmessage = (event) => {
  const { jobId, progress, status } = JSON.parse(event.data);
  console.log(`Job ${jobId}: ${progress}% - ${status}`);
};
4. Notifications (Planned)
  • Email alerts on job completion/failure
  • Discord webhooks
  • Pushover/Telegram integration
Mobile Access:
  • Enable port forwarding (3100, 4200)
  • Use VPN for secure remote access (Tailscale, WireGuard)
  • Or reverse proxy with SSL (Nginx, Caddy)
Example: Nginx Reverse Proxy
server {
  listen 443 ssl;
  server_name bitbonsai.yourdomain.com;

  location / {
    proxy_pass http://localhost:4200;
  }

  location /api {
    proxy_pass http://localhost:3100;
  }
}
See Monitoring Guide for dashboards.

​
Roadmap & Features

Not yet. This is a planned feature for v2.0.Requested Functionality:
  • Schedule encoding windows (e.g., 2 AM - 6 AM)
  • Pause all jobs during business hours
  • Limit CPU/GPU usage by time of day
  • Priority queue for specific libraries
Workarounds:
  1. Manual Pause/Resume
    • Pause all jobs before peak hours
    • Resume overnight
  2. Cron Script (API-Based) 
# Pause at 8 AM
0 8 * * * curl -X POST http://localhost:3100/api/queue/pause-all

# Resume at 6 PM
0 18 * * * curl -X POST http://localhost:3100/api/queue/resume-all
  1. CPU Limiting (Docker)
# docker-compose.yml
services:
  backend:
    cpus: '2.0'  # Limit to 2 cores
Vote for This Feature:ETA: Q2 2026 (tentative)
BitBonsai offers three tiers:
TierPriceMax NodesMax JobsFeatures
FREE$01 node1 jobSingle-node, basic features
SUPPORTER5/monthor5/month or 50/year3 nodes5 jobsMulti-node, priority support
PRO15/monthor15/month or 150/yearUnlimitedUnlimitedEnterprise features, SLA
Feature Comparison:
FeatureFREESUPPORTERPRO
LibrariesUnlimitedUnlimitedUnlimited
StorageUnlimitedUnlimitedUnlimited
Hardware Encoding✅✅✅
Multi-Node❌✅ (3 max)✅ (Unlimited)
Concurrent Jobs15Unlimited
Priority Support❌✅✅ + SLA
Discord Badge❌✅✅
Early Access❌✅✅
Commercial Use❌❌✅
Payment Options:
  • Stripe (credit card, monthly/yearly)
  • Patreon (monthly subscriptions)
  • Crypto (annual licenses only, contact sales)
Refund Policy:
  • 14-day money-back guarantee
  • Cancel anytime (no questions asked)
  • Downgrade keeps data intact
Purchase Link: bitbonsai.io/pricingNon-Profit/Educational Discounts: Contact [email protected] with proof of status for 50% discount.

​
Need More Help?

Still have questions? Try these resources: