Spyglass

Please note that we cannot support 32-bit systems. For more information please have a look at this comment.

A simple mjpeg server for the python module Picamera2.

With Spyglass you are able to stream videos from a camera that is supported by libcamera like the Raspberry Pi Camera Modules.

Current version: 0.18.0

Overview

• Quickstart
• Installation
• CLI arguments
• FAQ
  • How can I add CLI arguments to my spyglass.conf?
  • How to use resolutions higher than maximum resolution?
  • Why is the CPU load on my Pi5 so high?
  • How can I rotate the image of my stream?
  • How to apply tuning filter?
  • How to use the WebRTC endpoint?
  • How to use Spyglass with Mainsail?
  • How to use the controls endpoint?
  • How to start developing?

Quick Start

The server can be started with

./run.py

This will start the server with the following default configuration:

• Address the server binds to: 0.0.0.0
• Port: 8080
• Resolution: 640x480
• Framerate: 15 FPS
• Stream URL: /stream
• Snapshot URL: /snapshot
• WebRTC URL: /webrtc
• Controls URL: /controls

The stream can then be accessed at http://<IP of the server>:8080/stream.
You might need to install dependencies, refer to the installation section below.

Installation

Run following commands to install and run Spyglass as a service:

cd ~
sudo apt update
sudo apt install python3-libcamera python3-kms++ python3-picamera2 git -y
git clone https://github.com/mainsail-crew/spyglass
cd ~/spyglass
make install

This will ask you for your sudo password.
After install is done, please reboot to ensure service starts properly

To uninstall the service simply use

cd ~/spyglass
make uninstall

Use Moonraker Update Manager

To be able to use Moonraker update manager, add the following lines to your moonraker.conf:

[update_manager spyglass]
type: git_repo
path: ~/spyglass
origin: https://github.com/mainsail-crew/spyglass.git
primary_branch: main
virtualenv: .venv
requirements: requirements.txt
system_dependencies: resources/system-dependencies.json
managed_services: spyglass

Make sure moonraker.asvc contains spyglass in the list: cat ~/printer_data/moonraker.asvc | grep spyglass. If it is not there execute make upgrade-moonraker or add it manually

Configuration

After installation, you should find a configuration file in ~/printer_data/config/spyglass.conf.
Please see spyglass.conf for the default config file and CLI arguments for all available options.

Restart the service

To restart the service use systemctl:

sudo systemctl restart spyglass

CLI arguments

On startup the following arguments are supported:

| Argument | Description | Default | |--------------------------------|------------------------------------------------------------------------------------------------------------------------------------|--------------| | -b, --bindaddress | Address where the server will listen for incoming connections. | 0.0.0.0 | | -p, --port | Port where the server will listen for incoming connections. | 8080 | | -r, --resolution | Resolution of the captured frames. This argument expects the format <width>x<height>. | 640x480 | | -f, --fps | Framerate in frames per second (FPS). | 15 | | -st, --stream_url | Set the URL for the mjpeg stream. | /stream | | -sn, --snapshot_url | Set the URL for snapshots (single frame of stream). | /snapshot | | -w, --webrtc_url | Set the URL for WebRTC (H264 compressed stream). | /webrtc | | -af, --autofocus | Autofocus mode. Supported modes: manual, continuous. | continuous | | -l, --lensposition | Set focal distance. 0 for infinite focus, 0.5 for approximate 50cm. Only used with Autofocus manual. | 0.0 | | -s, --autofocusspeed | Autofocus speed. Supported values: normal, fast. Only used with Autofocus continuous. | normal | | -ud, --upsidedown | Rotate the image by 180° (see below). | | | -fh, --flip_horizontal | Mirror the image horizontally (see below). | | | -fv, --flip_vertical | Mirror the image vertically (see below). | | | -or, --orientation_exif | Set the image orientation using an EXIF header (see below). | | | -c, --controls | Define camera controls to start spyglass with. Can be used multiple times. This argument expects the format <control>=<value>. | | | -tf, --tuning_filter | Set a tuning filter file name. | | | -tfd, --tuning_filter_dir | Set the directory to look for tuning filters. | | | -n, --camera_num | Camera number to be used. All cameras with their number can be shown with libcamera-hello. | 0 | | -sw, --use_sw_jpg_encoding | Use software encoding for JPEG and MJPG (recommended on Pi5). | | | --disable_webrtc | Disable WebRTC encoding (recommended on Pi5). | | | --list-controls | List all available libcamera controls onto the console. Those can be used with --controls. | |

FAQ

How can I add CLI arguments to my spyglass.conf?

All supported CLI arguments are already inside the defaul config. If we add new arguments we will add them there, so please refer to it, if you want to use a new argument.

In the following sections we will only refer to the CLI arguments, but you can use the spyglass.conf for all these too.

How to use resolutions higher than maximum resolution?

Please note that the maximum recommended resolution is 1920x1080 (16:9).

The absolute maximum resolution is 1920x1920. If you choose a higher resolution spyglass may stop with Maximum supported resolution is 1920x1920. This is limited by the hardware (HW) encoder of the Pis.
You can disable this limit with --use_sw_jpg_encoding and --disable_webrtc, or the respective config in spyglass.conf, but it will take way more CPU resources to run the stream and WebRTC won't work anymore. Only a Pi5 you don't need to add --disable_webrtc, for further information please refer to Pi5 recommendations.

Why is the CPU load on my Pi5 so high?

The Pi5 is the newest generation of Raspberry Pi SBCs but not all new things come with improvements. The Raspberry Pi foundation decided to remove the hardware (HW) encoders from the Pi5. This results in overall higher CPU usage on a Pi5 compared to previous generations.

The following sections should only be followed on a Pi5.
WebRTC is also a big toll on your CPU. Therefore, you should use --disable_webrtc.
To reduce the CPU usage further you should add --use_sw_jpg_encoding to make sure to use the optimized software (SW) encoder, instead of the HW encoder falling back to an unoptimized SW encoder.

How can I rotate the image of my stream?

There are two ways to change the image orientation.

To use the ability of picamera2 to transform the image you can use the following options when starting spyglass:

• -ud or --upsidedown - Rotate the image by 180°
• -fh or --flip_horizontal - Mirror the image horizontally
• -fv or --flip_vertical - Mirror the image vertically

This will work with all endpoints Spyglass offers.

Alternatively you can create an EXIF header to modify the image orientation. Most modern browsers should respect the exif heade