Camera Streaming¶

Monitor your prints visually with live camera streaming directly from your Bambu Lab printer.

Live Streaming¶

Bambuddy provides MJPEG video streaming from your printer's built-in camera, or from an external network camera.

External Cameras¶

Connect external network cameras to replace the built-in printer camera. Useful for better angles, higher resolution, or printers in enclosures.

Supported Camera Types¶

Configuration¶

1. Go to Settings > General > Camera
2. Find your printer in the External Cameras section
3. Toggle the switch to enable
4. Enter the camera URL
5. Select the camera type
6. Click Test to verify connection

Features with External Cameras¶

Layer-Based Timelapse¶

When an external camera is enabled, Bambuddy automatically:

1. Captures a frame each time the print layer changes
2. Stores frames in a temporary directory during printing
3. Stitches video using ffmpeg when print completes
4. Attaches the timelapse to the print archive

Opening the Camera¶

1. Click the camera icon on any printer card
2. Camera opens based on your view mode setting (see below)
3. The stream starts automatically

View Mode Setting¶

Configure how camera streams open in Settings > General > Camera:

Embedded Viewer Features¶

When using embedded mode, the camera appears as a floating window:

• Draggable: Click and drag the header to reposition
• Resizable: Drag the bottom-right corner to resize
• Persistent: Position and size are remembered per printer across sessions
• Navigation Persistence: Open cameras stay open when navigating away and back to Printers page
• Minimize: Click the minimize button to collapse to title bar
• Close: Click X to close the viewer
• Multi-Viewer: Open cameras for multiple printers simultaneously

Stream Controls¶

Zoom & Pan¶

Zoom in on your camera feed to inspect print details.

Zoom Controls¶

Zoom range: 100% - 400%

Pan Controls¶

When zoomed in (>100%), you can pan around the image:

The pan range automatically adjusts based on zoom level - at higher zoom, you can pan further to explore the entire image.

Snapshot Mode¶

For lower bandwidth usage, use snapshot mode:

• Captures a single frame on demand
• Click refresh to get a new snapshot
• Ideal for cellular connections or slow networks

Technical Details¶

How Streaming Works¶

graph LR
    A[Printer Camera] -->|RTSP| B[ffmpeg]
    B -->|MJPEG| C[Bambuddy API]
    C -->|HTTP Stream| D[Browser]

1. Printer exposes camera via RTSP (Real Time Streaming Protocol)
2. ffmpeg converts RTSP to MJPEG (Motion JPEG)
3. Bambuddy serves the MJPEG stream to your browser
4. Browser displays frames in an <img> tag

Requirements¶

Installing ffmpeg¶

sudo apt install ffmpeg

brew install ffmpeg

Timelapse Editor¶

Edit timelapse videos directly in Bambuddy before downloading or sharing.

Opening the Editor¶

1. Go to Archives and select a completed print
2. Click on the timelapse video thumbnail
3. Click Edit to open the timelapse editor

Editing Features¶

Exporting¶

1. Make your edits
2. Click Export
3. Wait for processing (uses ffmpeg)
4. Download the edited video

Camera Snapshots on Print Complete¶

Bambuddy can automatically capture a camera snapshot when prints complete:

1. Go to Settings > General
2. Enable Capture snapshot on print complete
3. Snapshots are saved to the archive

This creates a visual record of your completed prints!

Build Plate Empty Detection¶

Automatically detect if objects are left on the build plate before a print starts. If detected, the print is immediately paused and you receive a notification.

How It Works¶

1. Calibrate - Capture reference images of your empty build plate
2. Enable - Toggle plate detection on for the printer
3. Auto-Check - When any print starts, Bambuddy compares the current camera view to your references
4. Auto-Pause - If objects are detected, the print is immediately paused

Calibration¶

Store up to 5 reference images per printer for different plate types (textured, smooth, high-temp, etc.):

1. Click the scan icon on the printer card to open the modal
2. Ensure the build plate is completely empty and chamber light is ON
3. Click Calibrate Empty Plate
4. Optionally add a label (e.g., "Textured PEI", "Cool Plate")
5. Repeat for other plate types you use

Enabling Detection¶

Use the split button on the printer card:

When enabled, the button shows a green border.

ROI (Region of Interest)¶

Adjust which part of the camera view is analyzed:

1. Open the plate detection modal
2. Scroll to Detection Area (ROI)
3. Click Edit
4. Use the sliders to adjust X, Y, Width, and Height
5. Click Save

The green box in the preview shows the detection area. Focus it on just the build plate to avoid false positives from the printer frame or background.

Managing References¶

In the plate detection modal:

• View thumbnails of saved references
• Click label to edit (e.g., "High Temp Plate")
• Click X on thumbnail to delete
• See timestamps for when each was calibrated

Notifications¶

When objects are detected:

• Print pauses immediately
• Toast notification appears in Bambuddy
• Push notification sent (if configured)
• WebSocket event broadcast for integrations

Requirements¶

How Detection Works¶

1. Captures current camera frame (or uses buffered frame if stream is active)
2. Applies heavy Gaussian blur to both current and reference images
3. Normalizes both images for consistent comparison
4. Extracts the ROI region
5. Calculates pixel difference percentage
6. If difference > 1%, plate is considered "not empty"

Troubleshooting¶

False Positives (detects objects when empty)

• Calibrate with chamber light ON (same as during prints)
• Adjust ROI to exclude printer frame edges
• Add multiple calibrations for different lighting conditions

False Negatives (doesn't detect objects)

• Ensure chamber light is ON
• Recalibrate - plate surface may have changed
• Check that objects are within the ROI area

Stream Settings¶

Frame Rate¶

The default frame rate is 15 FPS. You can adjust this in the URL:

/api/v1/printers/{id}/camera/stream?fps=20

Stream Cleanup¶

Bambuddy properly cleans up camera streams:

• Window close - Stream stops automatically
• Tab hidden - Stream pauses to save resources
• Page unload - ffmpeg process terminated
• Refresh - Old stream stopped, new one started

This prevents orphaned ffmpeg processes from consuming resources.

Auto-Reconnect¶

Bambuddy automatically detects and recovers from stalled camera streams:

Stall Detection¶

The browser periodically checks if the stream is still receiving frames:

• Check interval: Every 5 seconds
• Detection: Compares last frame timestamp
• Threshold: Stalled if no new frames for >5 seconds

Automatic Recovery¶

When a stall is detected:

1. Detects that no frames have been received
2. Closes the stalled connection
3. Reconnects automatically
4. Resumes streaming

Troubleshooting¶

Stream Won't Start¶

1. Is the printer on? Camera requires power
2. Is camera enabled? Check printer settings
3. Is ffmpeg installed? Required for streaming
4. Is Developer Mode enabled? Required for camera access
5. Running in Docker? Try network_mode: host if having issues

Docker: Camera Not Working¶

If camera streaming doesn't work in Docker, try host network mode:

# docker-compose.yml
services:
  bambuddy:
    build: .
    network_mode: host
    # Remove the ports: section when using host mode

Note: Docker's default bridge networking with NAT works in most setups. Host mode is only needed if your network configuration prevents NAT'd traffic from reaching the printer.

Stream Freezes¶

• Network congestion or WiFi issues
• Try lowering the FPS
• Check printer WiFi signal strength
• Try snapshot mode instead

High Latency¶

MJPEG streaming typically has 1-3 seconds of latency. This is normal and due to:

• RTSP buffering
• ffmpeg processing
• HTTP streaming

Camera Shows Black¶

• Camera may be initializing
• Try refreshing the stream
• Check if camera works in Bambu Studio

API Endpoints¶

For developers and integrations:

Example: Embed in OBS¶

Use the stream URL directly:

http://your-bambuddy-server:8000/api/v1/printers/1/camera/stream

Add as a Browser Source or Media Source in OBS.

Streaming Overlay for OBS¶

Bambuddy includes a dedicated overlay page designed for live streaming. It combines the camera feed with real-time print status in a single embeddable view.

Accessing the Overlay¶

Navigate to:

http://your-bambuddy-server:8000/overlay/{printer_id}

For example: http://192.168.1.100:8000/overlay/1

What's Included¶

The overlay displays:

OBS Setup¶

1. In OBS, click + under Sources
2. Select Browser
3. Enter the overlay URL (e.g., http://192.168.1.100:8000/overlay/1)
4. Set width and height to match your scene (e.g., 1920x1080)
5. Click OK

Customization¶

Customize the overlay using query parameters:

Size¶

/overlay/1?size=small
/overlay/1?size=medium   (default)
/overlay/1?size=large

Frame Rate (FPS)¶

Control the camera stream frame rate:

/overlay/1?fps=30

FPS is automatically clamped between 1 and 30. The backend may further limit based on camera type (A1/P1 cameras max out at ~5 FPS).

Status-Only Mode (No Camera)¶

Hide the camera feed and show only the status overlay on a black background:

/overlay/1?camera=false

This is useful for:

• Streamers who want status info without camera
• Low-bandwidth scenarios
• Creating a minimal status display

Set camera=false or camera=0 to hide the camera. Default is camera=true.

Show/Hide Elements¶

Control which elements are displayed:

/overlay/1?show=progress,layers,eta,filename,status

Available elements:

Examples:

# Show only progress and ETA
/overlay/1?show=progress,eta

# Show everything including printer name
/overlay/1?show=progress,layers,eta,filename,status,printer

# Minimal overlay - just progress
/overlay/1?show=progress

Combined Parameters¶

# Large overlay with max FPS
/overlay/1?size=large&fps=30&show=progress,eta,filename

# Status-only with selected elements
/overlay/1?camera=false&show=progress,eta,status

# Minimal status display
/overlay/1?camera=false&size=small&show=progress

Features¶

• Real-Time Updates - Status updates via WebSocket with polling fallback
• Auto-Reconnect - Camera stream automatically reconnects on errors
• Gradient Overlay - Text appears over a gradient for readability
• Responsive - Adapts to different browser source sizes
• Branding - Bambuddy logo always visible (links to GitHub)

Idle State¶

When no print is running, the overlay shows:

• Camera feed (still active)
• "Printer is idle" or "Printer offline" message
• Bambuddy logo

Troubleshooting¶

Overlay not loading in OBS

• Verify the URL works in a regular browser first
• Check that OBS can reach your Bambuddy server (same network)
• Try refreshing the browser source in OBS

Camera not showing

• Ensure the printer is connected
• Check that camera streaming works in Bambuddy directly
• The overlay uses the same camera stream as the main app

Status not updating

• WebSocket connection may have failed
• Overlay falls back to polling every 2 seconds
• Refresh the browser source to reconnect

Tips¶