Settings file#

This file controls how the camera behaves and how your buttons, switches and displays are mapped. It lives in ~/cinemate/src/settings.json. You can edit it with any text editor; the settings take effect the next time you start Cinemate.

The configuration is structured as JSON. Each top‑level key describes a feature area of the system. Below is a tour of every section and what the options do.

welcome message#

Text or image displayed briefly when Cinemate starts.

"welcome_image": null
"welcome_message": "THIS IS A COOL MACHINE",

Set welcome_image to the path of a bitmap file to show a logo instead of text.

Example path: /home/pi/welcome_image.bmp.

If welcome image path is set, this will override the text message.

system#

"system": {
  "wifi_hotspot": {
    "name": "CinePi",
    "password": "11111111",
    "enabled": false
  }
}

name – the Wi‑Fi network name (SSID) broadcast by the Pi when hotspot mode is enabled. password – password for joining the hotspot. enabled – set to true to start the hotspot automatically on boot. If set to false, CineMate will still start its web ui but stream it on whatever network the Pi is connected to.

Use the hotspot when you need a direct connection in the field. Disable it during development so the Pi can join your regular Wi‑Fi and reach the internet. If you are connected to the Pi via Ethernet you can keep the hotspot on.

geometry#

Controls image orientation for each camera port (cam0, cam1, etc.). These settings let you mount cameras in any orientation and still get an upright preview and recording. Example:

"geometry": {
  "cam0": { "rotate_180": false, "horizontal_flip": false, "vertical_flip": false },
  "cam1": { "rotate_180": false, "horizontal_flip": false, "vertical_flip": false }
}

rotate_180 – flip the image upside‑down.
horizontal_flip – mirror the image left/right.
vertical_flip – mirror the image top/bottom.

output#

Maps each camera to an HDMI connector. Use -1 for automatic selection.

"output": {
  "cam0": { "hdmi_port": 0 },
  "cam1": { "hdmi_port": 1 }
}

Use HDMI port 0 for HDMI-A-1 and HDMI port 1 for HDMI-A-2.

hdmi_gui#

Controls optional HDMI GUI overlays.

"hdmi_gui": {
  "buffer_vu_meter": false,
  "vu_meter_hatch_lines": true
}

buffer_vu_meter – show or hide the vertical RAM-buffer meter on the HDMI GUI.
vu_meter_hatch_lines – draw hatch lines inside the buffer meter fill.

hdmi_display#

Sets the preferred HDMI GUI canvas size.

"hdmi_display": {
  "width": 1920,
  "height": 1080
}

Use this to tell Cinemate what size GUI canvas you want to target. If the active framebuffer is smaller, Cinemate now falls back to the active framebuffer size instead of drawing a clipped 1920x1080 layout into a smaller mode.

preview#

Adjusts zoom levels for the HDMI/browser preview.

"preview": {
  "default_zoom": 1.0,
  "zoom_steps": [1.0, 1.5, 2.0]
}

default_zoom – magnification factor used at startup.
zoom_steps – list of zoom factors you can cycle through with the set_zoom_step command.

anamorphic_preview#

For stretching the preview when using anamorphic lenses.

"anamorphic_preview": {
  "default_anamorphic_factor": 1,
  "anamorphic_steps": [1, 1.33, 2.0]
}

default_anamorphic_factor – factor loaded when Cinemate starts.
anamorphic_steps – selectable squeeze factors; values above 1.0 widen the image.

gpio_output#

Defines pins used for visual feedback or sync signals.

"gpio_output": {
  "pwm_pin": 19,
  "rec_out_pin": [6, 21],
  "rec_tone_pin": [18],
  "rec_tone_frequency_hz": 1000,
  "rec_tone_duty_cycle": 50
}

• pwm_pin – outputs a strobe for shutter sync or external devices.

• rec_out_pin – list of pins pulled high while recording (useful for tally LEDs).

• rec_tone_pin – optional tone output pin(s) used as recording sync tone. You can pass a single pin or a list of pins.

• GPIO 18 and 19 use hardware PWM (preferred for stable tone generation).
• Any other pin uses software PWM fallback.
• The tone starts as soon as recording is requested (is_recording = 1), even before REC-light write confirmation.
• The tone stops once writing stops (is_writing = 0) and is muted during storage pre-roll.
• rec_tone_pin – optional tone output pin(s) that are active while recording. You can pass a single pin or a list of pins.
• GPIO 18 and 19 use hardware PWM (preferred for stable tone generation).

• Any other pin uses software PWM fallback.

• rec_tone_frequency_hz – tone frequency in hertz.

• rec_tone_duty_cycle – PWM duty cycle percentage (0–100).

• rec_tone_relay_drop_frames – when true, each live drop-frame pulse (drop_frame_relay = 1) briefly mutes REC tone output for about one frame, then resumes automatically.

arrays#

Preset lists for exposure and frame‑rate settings. Cinemate will step through these values unless you enable free mode, either in the settings file or during runtime.

"arrays": {
  "iso_steps": [100, 200, 400, 640, 800, 1200, 1600, 2500, 3200],
  "shutter_a_steps": [1, 45, 90, 135, 172.8, 180, 225, 270, 315, 346.6, 360],
  "fps_steps": [1, 2, 4, 8, 12, 16, 18, 24, 25, 33, 40, 50],
  "wb_steps": [3200, 4400, 5600]
}

settings#

General options for runtime behaviour.

"settings": {
  "light_hz": [50, 60],
  "conform_frame_rate": 24
}

light_hz – list of mains frequencies used to calculate flicker‑free shutter angles. These are added to the shutter angle array and also dynamically calculated upon each fps change. This way, there is always a flicker free shutter angle value close by, when toggling through shutter angles, either via the cli or using buttons/pots/rotary encoder.
conform_frame_rate – frame rate intendend for project conforming in post. This setting is not really used by CineMate except for calculating the recording timecode tracker in redis but might be used in future updates.

analog_controls#

Maps Grove Base HAT ADC channels to analogue dials (potentiometers). Use null to disable a dial.

"analog_controls": {
  "iso_pot": 0,
  "shutter_a_pot": 2,
  "fps_pot": 4,
  "wb_pot": "None"
}

free_mode#

When enabled, ignores the preset arrays and exposes the full range supported by the sensor.

"free_mode": {
  "iso_free": false,
  "shutter_a_free": false,
  "fps_free": true,
  "wb_free": false
}

resolutions#

Limit which sensor modes appear when cycling resolutions.

"resolutions": {
  "k_steps": [1.5, 2, 4],
  "bit_depths": [10, 12],
  "custom_modes": {
    "imx283": [
      {"width": 3936, "height": 2176, "bit_depth": 12, "fps_max": 24}
    ]
  }
}

k_steps – K‑style categories for allowed widths. Modes are grouped to the nearest half‑K. Example: 1332×990 counts as 1.5 K.
bit_depths – list of bit depths to expose.
custom_modes – optional extra modes per sensor if the driver advertises none.

buttons#

Defines GPIO push buttons. Each entry describes one button and the actions it triggers.

{
  "pin": 5,
  "pull_up": true,
  "debounce_time": 0.1,
  "press_action": {"method": "rec"}
}

pin – BCM pin number the button is connected to.
pull_up – set true if the pin idles high (internal pull‑up). Use false for pull‑down wiring.
debounce_time – ignore additional presses within this time window (seconds).
press_action, single_click_action, double_click_action, triple_click_action, hold_action – actions to perform for each type of interaction. Actions call Cinemate CLI commands with optional args.

two_way_switches#

Latching on/off switches. Cinemate triggers an action whenever the state changes.

{
  "pin": 27,
  "state_on_action":  {"method": "set_all_lock", "args": [1]},
  "state_off_action": {"method": "set_all_lock", "args": [0]}
}

rotary_encoders#

Rotary encoders used for fine adjustment of settings. These can be wired straight to the GPIO pins of the Pi.

{
  "clk_pin": 9,
  "dt_pin": 11,
  "encoder_actions": {
    "rotate_clockwise":        {"method": "inc_iso"},
    "rotate_counterclockwise": {"method": "dec_iso"}
  }
}

clk_pin and dt_pin – the two pins of the encoder.
encoder_actions – commands to run when turning the dial.

quad_rotary_controller#

Support for the Adafruit Neopixel Quad I2C rotary encoder breakout. Each entry maps one of the four dials to a setting and defines the push button actions similar to the buttons section.

"quad_rotary_controller": {
  "enabled": true,
  "encoders": {
    "0": {"setting_name": "iso", "button": {"press_action": {"method": "rec"}}},
    "1": {"setting_name": "shutter_a", "button": {"press_action": {"method": "set_fps_double"}}},
    "2": {
      "setting_name": "fps",
      "button": {
        "press_action": "None",
        "single_click_action": {"method": "set_resolution"},
        "double_click_action": {"method": "restart_cinemate"},
        "triple_click_action": {"method": "reboot"},
        "hold_action": {"method": "toggle_mount"}
      }
    },
    "3": {"setting_name": "wb", "button": {"press_action": {"method": "rec"}}}
  }
}

enabled – turn the quad rotary controller on or off.
encoders – mapping of each dial to a setting and button actions.

i2c_oled#

Configuration for the optional OLED status screen. This can be useful for presenting extra information appart from the HDMI/web display.

"i2c_oled": {
  "enabled": true,
  "width": 128,
  "height": 64,
  "font_size": 30,
  "values": ["write_speed_to_drive"]
}

enabled – turn the OLED display on or off. width / height – pixel dimensions of your screen. font_size – size of the displayed text. values – list of Redis keys or pseudo‑keys to show (for example cpu_temp).

Available keys come from src/module/i2c/i2c_oled.py. Here are some examples:

iso, fps – basic camera settings.
shutter_a – shown as SHUTTER with a ° suffix.
wb_user – shown as WB with a trailing K.
space_left – displayed as SPACE in gigabytes.
write_speed_to_drive – write speed in MB/s.
resolution – prints width×height@bit_depth on the first line.
is_recording – draws a bullet ● when recording.
cpu_load, cpu_temp, memory_usage – Pi system statistics.

Other keys will display their name in uppercase and the raw value from Redis.