To build a Dream Recorder, these are the components you will need. The overall cost for these components from the provided links is approximately €285 (Last updated May 2025).

In order to generate dreams, this application uses OpenAI and LumaLabs' APIs. The approximate costs are as follows (last updated May 2025):

• OpenAI text-to-speech and video prompt generation: < $ 0.01 per dream - OpenAI Pricing
• LumaLabs dream generation (using 540p, 21:9, 5 seconds, ray-flash-2): $ 0.14 per dream - LumaLabs Pricing

📄 Assembly Guide (PDF)

• Download and install the Raspberry Pi imager software - https://www.raspberrypi.com/software/
• Plug the micro SD card into your computer using an SD card reader
• Open the Raspberry Pi imager software and install it using the following details:
  • Raspberry Pi OS (64-bit)
  • Choose to edit the customisation settings
    • General:
      • Hostname: dreamer
      • Username: dreamer
      • Password: (choose a simple password)
      • Type in your WiFi network's SSID & password carefully
    • Services: Enable SSH using password authentication
• Once the installation has finished, safely eject and remove the microSD card

See step-by-step images 🖼️

• Insert the microSD card into the Raspberry Pi
• Plug the Raspberry Pi in using the power supply and wait for it to boot up

You now need to find the IP address that your local network has assigned to the Raspberry Pi. You can do this in one of three ways:

1. EASY: On the device:
   • Plug a USB mouse in to the Raspberry Pi
   • Click on the Wifi icon on the top right of the screen
   • Advanced Options -> Connection Information
   • Note the IP address (e.g. 192.168.1.100)
   • ...or...
2. MEDIUM: On your network router's admin software interface:
   • This approach's exact steps will depend on what your home network's router and software is
   • Essentially you will need to find all connected devices and find the Raspberry Pi
   • ...or...
3. HARD: In a Terminal console on your computer:
   • Open up a terminal window
   • Check if you have nmap installed by running:
     • nmap
     • If it's not installed, do so now - Downloads & instructions
   • Find your computer's IP by either:
     1. Running this command in the terminal:
        • ifconfig | grep "inet "
        • Make a note of your computer's IP address (which will most likely look something like 192.168.X.X)
        • ...or...
     2. Referring to your computer's Wifi / Ethernet connection details via settings
   • Run this command in the terminal, keeping the first three numbers sets the same as your computer's IP and leaving the 0/24 at the end:
     • nmap -sn 192.168.1.0/24 | grep dreamer
     • So if your computer's IP address is 192.168.1.100 for example, you would run: nmap -sn 192.168.1.0/24 | grep dreamer

• Open up a terminal / command line / bash window
• SSH into the Dream Recorder with the following command, using the simple password you created in the Raspberry Pi imager:
  • ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
• Run the Raspberry Pi config tool by running this command:
  • sudo raspi-config
  • Interface Options -> VNC -> Yes -> OK
  • Localisation Options -> Configure time zone -> Choose your country & city
  • Select <Finish>
• Keep this terminal window open for later

See step-by-step images 🖼️

• Download RealVNC, install and run it
  • Connect to the Dream Recorder using the hostname (dreamer), the username (dreamer) and your simple password
  • You now have remote desktop access to the Raspberry Pi
  • Change the screen's orientation:
    • Click the Raspberry Pi icon (top left) -> Preferences -> Screen Configuration
    • Right click on the HDMI-A-1 screen -> Orientation -> "Right" -> OK
    • Drag the window to the left so you can click the "Apply" button
    • Navigating with the mouse might become tricky now, so you can use your keyboard as follows:
      • <tab> <tab> <spacebar>
  • Close RealVNC

See step-by-step images 🖼️

• Generate an API key for OpenAI:
  • Login / sign up to OpenAI and create a secret / API key
  • Copy the value and paste it to a text file temporarily as you will need it shortly
  • Add a few dollars of credits to your account (~$5 suggested)
• Generate an API key for LumaLabs:
  • Login / sign up to LumaLabs and create a secret / API key
  • Copy the value and paste it to a text file temporarily as you will need it shortly
  • Add a few dollars of credits to your account (~$20 suggested)
• Copy the URL of the Git repository at the top of this Github page by clicking on the Code button at the top right and copying the 'HTTP' url

• Make sure you are still connected to the Dream Recorder
  • If not, connect again:
    • ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
• Clone the Dream Recorder from Github using the URL you just copied in the step above
  • git clone <repo_ssh_url>
• Once completed, navigate into the repo folder:
  • cd dream-recorder
• Run the installer:
  • ./pi_installer.sh
  • When prompted, paste in each of the API keys you generated above
• Reboot the Raspberry Pi: sudo reboot
• You are now up and running once the Pi has rebooted!

• Single tap: Play the latest dream
  • Single tapping while a dream is playing will play the previous dream
  • Double tapping while a dream is playing will go back to clock mode
• Double tap: Record a dream
  • Single tap once you are done talking for the dream to be generated

You should be good to go with your Dream Recorder now! Everything below is mostly for those that want to take things further to start tinkering and contributing

To change the default settings for the Dream Recorder, you can use the command line configuration tool:

• SSH into the Dream Recorder with the following command, using the simple password you created in the Raspberry Pi imager:
  • ssh dreamer@<DREAM_RECORDER_IP_ADDRESS>
• Navigate to the Dream Recorder's root folder:
  • cd dream-recorder
• Run this command: ./dreamctl config
• After saving (s) and quitting (q), reload the application (if you've changed any core, non-superficial configurations) by running:
  • docker compose restart

In the ./3DAssets folder you will find STL and G-code files for the translucent two-part 3D-printable enclosure. Designed with accessibility in mind, it should print reliably on most FDM printers using basic slicer settings.

G-code was sliced for a 0.4 mm nozzle with standard PLA settings at 0.2 mm layer height.

Note: Prime tower is disabled to ensure simplicity and material efficiency.

• Optimized for standard 0.2 mm settings, but prints well across a range of layer heights
• You can use your own slicer or directly print using the included .gcode files (assuming printer compatibility)

1. Print both front and back pieces
2. Remove supports carefully (tree structures minimize scarring)
3. Clean up seam edges with light sanding if needed
4. Press-fit the two parts together (t)he enclosure is designed for a friction fit, so no glue or fasteners required)

• Note: You will need Docker (Compose) installed on your system - Docker documentation

git clone <repo_url>
cd dream-recorder
cp ./.env.example ./.env
cp ./config.example.json ./config.json
# Add your API keys using vim, nano or any text editor you're compfortable with
vim .env
docker compose -f docker-compose.dev.yml build
docker compose -f docker-compose.dev.yml up -d
# Edit the default config options (optional)
./dreamctl config

The app will be available at http://localhost:5000 (unless you choose to change the default port in the config)

To simulate sensor button presses, you can either use the on-screen developer console (available when running in dev mode), or:

• Note: You will need Python 3.12 installed on your system - Python documentation

python gpio_service.py --test

See step-by-step images 🖼️

Run this command to run the tests:

• ./dreamctl test Run this command to run the tests and see overall test coverage:
• ./dreamctl test-cov

To see how the application's architecture and communication works visually, please refer to the Mermaid diagrams:

• 📈 Application Architecture
• 📈 Conversation flow

You can access the dream management page from your computer by going to http://dreamer:5000/dreams

See step-by-step images 🖼️

• Logs:
  • App logs: docker compose logs -f
  • GPIO logs: ./dreamctl gpio-logs (for on the Dream Recorder)
  • GPIO logs: tail -f logs/gpio_service.log (for during development on your local machine if using python gpio_service.py --test)
• Check running services:

  docker ps
  ps aux | grep gpio_service.py
  ps aux | grep chromium-browser

• Stop the services:

  docker compose down
  systemctl --user stop dream_recorder_gpio.service

• Restart the services:

  docker compose up -d
  systemctl --user start dream_recorder_gpio.service

To make working with the Dream Recorder easier, you can use the dreamctl script in the project root. This script simplifies running common commands inside the Docker container.

Usage:

./dreamctl <command>

Available commands:

• config Edit the Dream Recorder configuration
• test Run unit tests
• test-cov Run unit tests with coverage report
• gpio-logs Tail the GPIO service log (logs/gpio_service.log)
• help Show help message

For example:

• ./dreamctl config will open the configuration editor
• ./dreamctl test will run the test suite
• ./dreamctl test-cov will run the test suite with coverage reporting
• ./dreamctl gpio-logs will tail the GPIO service log (logs/gpio_service.log)

You can extend dreamctl to add more commands as needed.

If you would like to contribute to the project, here are some areas we would love help / contribution towards:

• Improving on the shopping list:
  • Including better, more local options (globally) that are not Amazon
  • Finding more efficient purchases for larger packaged items, such as the Dupont cables, nylon screwsets, etc...
• Building out support for multiple (by configuration) AI providers:
  • Support for alternative STT and/or prompt generation providers (Claude, Gemini, etc...)
  • Support for alternative video generation providers
• Adding in support for config-based screen-blanking between configurable times

Open an issue or contact the lead maintainer for help:

@markhinch

Dream Recorder is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE.md file in the project repository.