# How SD Card Recording Mode Switching Works in AtomCam: Direct Write vs RAM-Disk

> Understand how AtomCam switches between RAM-disk buffering and direct SD card recording. Learn about runtime file path rewriting for efficient video capture.

- Repository: [Mitsuru Nakada/atomcam_tools](https://github.com/mnakada/atomcam_tools)
- Tags: internals
- Published: 2026-03-07

---

**AtomCam switches between RAM-disk buffering and direct SD-card writes by rewriting file paths at runtime based on a user-configurable flag that propagates from the web UI through boot scripts to a native callback library.**

The **mnakada/atomcam_tools** project implements a three-tier architecture to control **SD card recording mode switching**. Users can choose between writing video temporarily to a RAM-disk (`/tmp`) for later synchronization or streaming directly to the SD card (`/media/mmc/tmp`), balancing wear leveling against memory usage. The system modifies encoder output paths dynamically without requiring filesystem mounts or application restarts.

## UI Configuration Layer (web/source/vue/Setting.vue)

The recording mode originates in the web interface as a toggle switch bound to the configuration key `STORAGE_SDCARD_DIRECT_WRITE`. In [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue), the component stores the user selection and persists it to [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini) on the device.

- **Line 214**: The `SettingSwitch` component binds to `config.STORAGE_SDCARD_DIRECT_WRITE`, presenting the option in the Media settings tab.
- **Line 495**: The default value initializes as `'off'`, meaning RAM-disk mode is the factory default.

```html
<!-- web/source/vue/Setting.vue -->
<SettingSwitch i18n="SDCardSettings.directWrite"
               v-model="config.STORAGE_SDCARD_DIRECT_WRITE" />

```

When toggled, the value (`on` or `off`) writes to [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini):

```ini
STORAGE_SDCARD_DIRECT_WRITE=on   # Enables direct SD-card writes

```

## Boot-Time Mode Selection (overlay_rootfs/scripts/set_icamera_config.sh)

During system startup, [`overlay_rootfs/scripts/set_icamera_config.sh`](https://github.com/mnakada/atomcam_tools/blob/main/overlay_rootfs/scripts/set_icamera_config.sh) reads the persisted flag and translates it into operational modes for periodic and alarm recordings. The script evaluates independent settings for each recording type before issuing the native command.

**Lines 36-42** implement the logic:

```sh

# overlay_rootfs/scripts/set_icamera_config.sh

STORAGE_SDCARD_DIRECT_WRITE=$(awk -F "=" '/^STORAGE_SDCARD_DIRECT_WRITE *=/ {print $2}' $HACK_INI)

PERIODIC="ram"
ALARM="ram"

if [ "$STORAGE_SDCARD_DIRECT_WRITE" = "on" ] ; then
  [ "$PERIODICREC_SDCARD" = "on" ] && PERIODIC="sd"
  [ "$ALARMREC_SDCARD"   = "on" ] && ALARM="sd"
fi

/scripts/cmd mp4write $PERIODIC $ALARM > /dev/null

```

The script passes two arguments to the `mp4write` command: the first controls periodic recording storage, and the second controls alarm recording storage. Valid values are `sd` (direct write) or `ram` (RAM-disk buffer).

## Native Path Rewriting (libcallback/mp4write.c)

The `mp4write` command is implemented in [`libcallback/mp4write.c`](https://github.com/mnakada/atomcam_tools/blob/main/libcallback/mp4write.c) as the function `MP4Write()`. This native callback intercepts the encoder's file creation requests and rewrites paths based on static flags set during boot.

**Lines 27-55** store the mode selection in global flags:

```c
// libcallback/mp4write.c
char *MP4Write(int fd, char *tokenPtr) {
    char *p = strtok_r(NULL, " \t\r\n", &tokenPtr);
    char *q = strtok_r(NULL, " \t\r\n", &tokenPtr);
    
    if(!strcasecmp(p, "sd")) 
        mp4write_periodicSD = 1;
    else if(!strcasecmp(p, "ram")) 
        mp4write_periodicSD = 0;
        
    if(!strcasecmp(q, "sd")) 
        mp4write_AlarmSD = 1;
    else if(!strcasecmp(q, "ram")) 
        mp4write_AlarmSD = 0;
        
    return "ok";
}

```

When the video encoder initiates recording, `mp4write_start_handler()` (lines 57-66) inspects the destination path and rewrites it for direct-write mode:

```c
// libcallback/mp4write.c
int mp4write_start_handler(void *handler, char *file, struct Mp4StartConfig *config) {
    if((mp4write_AlarmSD && !strncmp(file, "/tmp/alarm_", 11)) ||
       (mp4write_periodicSD && !strncmp(file, "/tmp/", 5) && (strlen(file) == 11))) {
        char buf[64];
        strncpy(buf, file + 5, 30);          // Extract filename without /tmp/
        strcpy(file, "/media/mmc/tmp/");     // Set SD-card base path
        strcat(file, buf);                   // Append original filename
    }
    // ... proceed to original handler with modified path
}

```

- **RAM-disk mode**: Files remain under `/tmp/...` and are synchronized to the SD card by a background copy task.
- **Direct-write mode**: The handler transforms `/tmp/alarm_12345.mp4` into `/media/mmc/tmp/alarm_12345.mp4`, causing the hardware encoder to write directly to the SD card and bypass the RAM buffer entirely.

## Summary

- The **Vue.js frontend** ([`Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/Setting.vue)) exposes the toggle and stores `STORAGE_SDCARD_DIRECT_WRITE` in [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini).
- The **boot script** ([`set_icamera_config.sh`](https://github.com/mnakada/atomcam_tools/blob/main/set_icamera_config.sh)) translates the configuration into `sd` or `ram` arguments for the native `mp4write` command.
- The **C callback library** ([`mp4write.c`](https://github.com/mnakada/atomcam_tools/blob/main/mp4write.c)) maintains two static flags (`mp4write_periodicSD`, `mp4write_AlarmSD`) and rewrites encoder output paths from `/tmp` to `/media/mmc/tmp` when direct-write mode is active.
- The system requires a reboot to apply changes because the configuration script runs only during initialization.

## Frequently Asked Questions

### What is the default recording mode in atomcam_tools?

The default configuration initializes `STORAGE_SDCARD_DIRECT_WRITE` to `'off'` in [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue) (line 495). This activates RAM-disk mode, where recordings are buffered in `/tmp` and later synchronized to the SD card by a background process.

### Does switching between direct write and RAM-disk require a reboot?

Yes. The [`set_icamera_config.sh`](https://github.com/mnakada/atomcam_tools/blob/main/set_icamera_config.sh) script executes only during system startup to invoke the `mp4write` command. Changing the toggle in the web UI updates [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini), but the device must restart for the shell script to read the new value and configure the native callback flags.

### How does the system distinguish between periodic and alarm recordings?

The `mp4write_start_handler()` function in [`libcallback/mp4write.c`](https://github.com/mnakada/atomcam_tools/blob/main/libcallback/mp4write.c) uses separate boolean flags (`mp4write_periodicSD` and `mp4write_AlarmSD`) and path prefix checks. Alarm recordings are identified by the `/tmp/alarm_` prefix, while periodic recordings match `/tmp/` with exactly 11-character filenames, allowing independent mode selection for each recording type.

### What are the performance implications of each mode?

**RAM-disk mode** reduces SD-card wear by batching writes and minimizes latency spikes during encoding, but consumes system RAM to buffer video. **Direct-write mode** eliminates the background copy step and reduces memory pressure, but increases write cycles on the SD card and may introduce latency if the card experiences slow erase cycles during recording.