https://github.com/gruvw/pireplay
Capture and instantly replay the last moments by using a web application controlling a Raspberry Pi with a camera.
https://github.com/gruvw/pireplay
camera cli python3 raspberry-pi rpi
Last synced: about 1 year ago
JSON representation
Capture and instantly replay the last moments by using a web application controlling a Raspberry Pi with a camera.
- Host: GitHub
- URL: https://github.com/gruvw/pireplay
- Owner: gruvw
- Created: 2024-06-10T11:42:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-26T14:36:08.000Z (about 1 year ago)
- Last Synced: 2025-06-19T02:15:52.879Z (about 1 year ago)
- Topics: camera, cli, python3, raspberry-pi, rpi
- Language: Python
- Homepage: https://pypi.org/project/pireplay
- Size: 3.56 MB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
# PiReplay
Capture a video and instantly replay the last moments from your phone or computer.
PiReplay is a device that allows you to instantly record and replay the past 5 to 60 seconds of real-life events directly from your phone or computer.
This has unlimited applications but is primarily useful when analyzing key moments in sports, capturing trick shots, reviewing gameplay, or simply reliving funny moments.
You simply press a button and instantly get a video of the last few seconds that just happened - live replay, IRL.
The device comes in two variants:
PiReplay~100x75x45mm
PiReplay Mini~80x40x25mm
You can capture replays from a locally hosted web application `pireplay.local`, which controls a [Raspberry Pi](https://www.raspberrypi.com) with a camera.
Take a look at the project's [roadmap](docs/roadmap.md) to see upcoming features (along with all the work accomplished).
**Note** - Check out the `pireplay` [Python](https://www.python.org) package (CLI) on PyPI: (managed using [Poetry](https://python-poetry.org/)).
## User Guide
1. Make sure you stand close to a running PiReplay device.
2. Using your phone or computer, connect to the PiReplay Wi-Fi network, usually named `PiReplay-XXXX` (the default password is `pireplay42`).
3. Open a web browser and navigate to the following URL `http://pireplay.local` or `http://10.42.0.1` (you might need to accept security warning).
4. Congratulations, you can now use the Web interface to capture, watch and download live replays!
Features:
- Press the **CAPTURE** button to save an instant replay save (you might need to wait a few seconds after pressing the button for the page to reload, avoid double pressing the CAPTURE button).
- Browse and watch past replays.
- Download replays directly to your phone or computer for saving and sharing them.
- Access the settings page to change the replay duration and camera resolution.
- Snapshot picture in the settings page for camera positioning.
- Vertical/horizontal videos support
- RESTful API to interoperate with other components of your digital system.
**Warning** - There are currently no security feature built in the PiReplay software. You should consider that anyone accessing the PiReplay's network could be accessing replays and remotely operate the device.
This project is **not** (out of scope features or non-goals):
- A live webcam feed.
- A continuous video camera for long videos.
- A video editor, editing must be done externally after downloading the replay.
- A multi-camera synchronization system, only one camera per device is supported.
- A home security video recording system.
- A motion triggered or AI-based capture system, you must manually trigger replays.
### User Interface
Web user interface from a phone:
## Project Structure
A brief overview of the project's structure for quick reference:
- [`cad`](./cad/): for 3D models files, 3D printing (case)
- [`src`](./src/): the source code of the Python `pireplay` package
## Do It Yourself
Follow these instructions (tutorial) for setting up a fully functional **PiReplay** device.
**PiReplay vs. PiReplay Mini**
The PiReplay Mini (~4 times smaller) was introduced into the project as a fun and compact alternative for space-constrained applications.
However, it uses a smaller, resource limited microcomputer, making it not the best choice to perform high resolution video processing.
Therefore, I recommend building the standard version of the PiReplay if space isn't a concern.
### Requirements
- Raspberry Pi board (recommended board: `Raspberry Pi 5 4GB` for PiReplay, or `Raspberry Pi Zero 2 W` for PiReplay Mini)
- Cooling system (optional, better for the `Raspberry Pi 5`: Raspberry Pi Active Cooler for Pi 5)
- Micro SD card (at least 64 GB)
- Raspberry Pi Camera module 3 (regular 75° sensor)
- CSI Camera FPC connector cable to Raspberry Pi (select the correct one depending on you Raspberry Pi board)
- Raspberry Pi power supply (Micro USB/USB type C), ensuring sufficient voltage
- PiReplay box (see below), 3D printer
- A 1/4"-20 UNC nut (optional, for mounting on a camera tripod)
### PiReplay box
You can 3D print the corresponding enclosure for the PiReplay device.
**Note** - Check out the project on Thingiverse: .
#### PiReplay
For the standard variant of the PiReplay (using the `Raspberry Pi 5`), choose one of the following base options:
- With a standard tripod camera mount (1/4"-20 UNC): [`./cad/pireplay/PiReplay-base_camera_mount.stl`](./cad/pireplay/PiReplay-base_camera_mount.stl)
- With rail screw mounts: [`./cad/pireplay/PiReplay-base_screw_mount.stl`](./cad/pireplay/PiReplay-base_screw_mount.stl)
The top cover piece is common for both:
- For horizontal videos: [`./cad/pireplay/PiReplay-cover.stl`](./cad/pireplay/PiReplay-cover.stl).
- For vertical videos: [`./cad/pireplay/PiReplay-cover-vertical.stl`](./cad/pireplay/PiReplay-cover-vertical.stl).
**Note** - This print is specifically designed to clip and assemble together, with no additional screws or glue needed. The Raspberry Pi board clips into place, the camera & nut slide into place (held by friction), and the cover snaps onto the base like a buckle clip.
#### PiReplay Mini
For the PiReplay Mini, you need to print the base and the cover:
- Base: [`./cad/pireplay_mini/PiReplay_mini-base.stl`](./cad/pireplay_mini/PiReplay_mini-base.stl)
- Cover for horizontal videos: [`./cad/pireplay_mini/PiReplay_mini-cover.stl`](./cad/pireplay_mini/PiReplay_mini-cover.stl)
- Cover for vertical videos: [`./cad/pireplay_mini/PiReplay_mini-cover-vertical.stl`](./cad/pireplay_mini/PiReplay_mini-cover-vertical.stl)
**Note** - The Mini version is designed for minimal space usage. You may need glue to secure the parts and keep the case closed.
### Quick Raspberry Pi Basic Setup
Install and configure Raspberry Pi OS for PiReplay on the board:
1. Download and install the Raspberry Pi OS Imager:
2. Connect the SD card to your computer and flash the OS on the card using Raspberry Pi OS Imager
1. _Raspberry Pi Device_: select your correct device (`Raspberry Pi 5`, `Raspberry Pi Zero 2 W`, ...)
2. _Operating System_: Raspberry Pi OS (other) > `Raspberry Pi OS Lite (64-bit)`
3. _Storage_: Select SD card
4. _Next_ > Edit Settings (additional configuration)
- General > Set hostname: `pireplay.local`
- General > Set username and **password**: `pireplay` (use a secure password)
- General > Configure wireless LAN: use your current Wi-Fi network credentials (only for setup purposes, we will use a Wi-Fi Hotspot configuration later).
- Services > Enable SSH (using password authentication)
5. Flash the SD card and wait till it completes
3. Insert the SD card inside the Raspberry Pi and power it using the micro USB cable (wait a few seconds)
4. Connect to your Raspberry Pi using an SSH client (on the same Wi-Fi network credentials used in the configuration)
- You can connect using [Putty](https://www.putty.org/), or simply running `ssh` from your terminal
- Connect using `pireplay@pireplay.local` as the host (use port 22)
- Enter the password you specified in Pi OS Imager during configuration
You are now connected via SSH to your newly setup Raspberry Pi for PiReplay.
### PiReplay Software Setup
After connecting to the Raspberry Pi via SSH, you can install and configure the `pireplay` software to run on it.
```bash
# Update/upgrade packages
sudo apt update
sudo apt upgrade -y
# Install requirements
sudo apt install -y python3-picamera2 --no-install-recommends
sudo apt install -y ffmpeg python3-pip
# Install PiReplay
sudo pip install pireplay --break-system-packages # or build/install from source
# Launch PiReplay automatically on reboot
(crontab -l 2>/dev/null; echo "@reboot sudo pireplay run") | crontab -
sudo reboot
```
Congratulations! Your PiReplay device is now fully functional.
#### Build from source (optional)
If you prefer to build and install the PiReplay package from source (on the Raspberry Pi), use the following:
```bash
sudo apt install -y git
git clone --depth 1 https://github.com/gruvw/pireplay
cd pireplay/src
poetry build
sudo pip install dist/pireplay-X.X.X.tar.gz --break-system-packages
```
**Note** - Requires [Poetry](https://python-poetry.org/).
### Configuration
You can configure some options of the `pireplay` program by providing a [YAML](https://yaml.org/) configuration file to the CLI: `pireplay run --config /path/to/config.yaml`.
Check the documented default config file as an example: [`./src/pireplay/default_config.yaml`](./src/pireplay/default_config.yaml).
**Note** - Vertical video rotation (when using the vertical camera attachement cover variant) must be explicitly set in the config file.
The PiReplay CLI saves the previous config (and UI set) parameters that were last used and will keep them on the next launch and across reboots (if not overwritten by passed config).
It might induce confusion as removing a line from your config file won't yield the same result as when it was not present in the first place.
If you want the default value of a config option, please refer to the [`./src/pireplay/default_config.yaml`](default_config.yaml) file.
### API
If you wish to integrate PiReplay into a larger system (like streaming, robotics, ...), there is an API to access its functionality from other programs or scripts.
Main endpoints:
- `/capture` (POST): triggers a replay capture, sends the raw replay URL in the `Raw-Replay` response (redirect) header.
- `/raw-replay/.mp4` (GET): access video file of a given replay.
- `/snapshot` (POST): triggers an instantaneous snapshot picture, sends raw snapshot URL in `Raw-Snapshot` response (redirect) header.
- `/raw-snapshot.jpg` (GET): the jpg picture of the instantaneous snapshot.
- `/settings/capture-time` (POST, form data `index` set to the index of capture time options, see configuration file): changes the replay duration.
- `/delete-replay` (POST, form data `replay` set to ``): deletes a given replay.
- `/delete-all-replays` (POST): deletes every replay.
### Troubleshooting
If you encounter network issues on your device, you might want to use SSH over USB to fix them.
Follow this tutorial to enable SSH over USB: .
## Contributions
Feel free to contribute by submitting pull requests, whether to add new features, improve existing functionality, or fix bugs :)
Before opening a new PR, please open an issue to discuss it beforehand (check for existing issues first).
## Powered by
This project would not be possible without the wonderful technologies below:
* [Python](https://www.python.org/)
* [Flask](https://github.com/pallets/flask/)
* [Raspberry Pi](https://www.raspberrypi.com/)
* [picamera2](https://github.com/raspberrypi/picamera2)