Open Ephys Data Format Converter

A standalone Windows x64 tool for converting neural recordings among the three data formats supported by the Open Ephys GUI:

• Open Ephys Binary Format (structure.oebin, continuous.dat, NumPy metadata)
• legacy Open Ephys Format (.continuous, .timestamps, .events, .openephys)
• NWB 2.x / HDF5 (.nwb)

No Python installation is required. Input recordings are opened read-only and are never modified, moved, deleted, or uploaded.

中文说明： 请参阅 README.zh-CN.md。下载 Release 中的 Windows x64 EXE 后即可使用，无需安装 Python 或配置运行环境。为保证仓库安全，请勿将原始实验数据、私有路径、密码、访问令牌或其他敏感信息提交到本仓库。

Repository safety: do not commit raw recordings, credentials, secrets, access tokens, private filesystem paths, or generated data containing sensitive information. See SECURITY.md.

Conversion matrix

Input \ Output	Binary	legacy Open Ephys	NWB 2.x / HDF5
Binary	—	✓	✓
legacy Open Ephys	✓	—	✓
NWB 2.x / HDF5	✓	✓	—

Format definitions are documented in the Open Ephys GUI data-format guide.

Features

• Guided setup when the EXE is double-clicked: choose a source, confirm the detected format, select a destination format, and review the conversion plan.
• Script-friendly CLI with explicit input, output, source format, destination format, and overwrite behavior.
• A single-line progress bar that refreshes in place instead of scrolling the terminal; redirected output automatically uses plain, low-frequency progress messages.
• Overall percentage, processed size, throughput, elapsed time, and estimated remaining time.
• Batch discovery of one or more legacy Open Ephys Record Nodes.
• Conversion of continuous signals, sample numbers, timestamps, channel metadata, scaling values, and TTL events.
• Structural metadata generation, including structure.oebin, legacy XML, conversion manifests, and completion flags where applicable.
• Standalone Windows x64 executable built with CGO disabled.

Quick start

1. Download the Windows x64 executable from the latest release.
2. Double-click the EXE.
3. Enter or drag the source file/folder into the terminal window.
4. Choose the destination format and path.
5. Review the plan and confirm the conversion.

The guided interface resembles:

----------------------------------------------------------------------
  Open Ephys Data Format Converter  vX.Y.Z
  legacy Open Ephys  <->  Binary  <->  NWB 2.x/HDF5
----------------------------------------------------------------------
Guided setup
Source path: D:\recordings\Record Node 101
  Detected: legacy Open Ephys Format
Destination format:
  1) Open Ephys Binary Format
  2) NWB 2.x / HDF5
Choose [1]:

The program proposes a destination beside the source. It asks before replacing an existing destination and shows the complete conversion plan before starting.

Examples below use OpenEphysDataFormatConverter.exe for readability. You may rename the downloaded file or substitute its full release filename.

Command-line usage

Use explicit options for scripts and reproducible workflows:

OpenEphysDataFormatConverter.exe `
  --from open-ephys `
  --to binary `
  --input "D:\recordings\legacy" `
  --output "E:\converted\binary"

Other examples:

# Binary -> legacy Open Ephys
OpenEphysDataFormatConverter.exe --from binary --to open-ephys -i "D:\binary" -o "E:\legacy"

# Binary -> NWB
OpenEphysDataFormatConverter.exe --from binary --to nwb -i "D:\binary" -o "E:\recording.nwb"

# NWB -> Binary with automatic input detection
OpenEphysDataFormatConverter.exe --from auto --to binary -i "D:\recording.nwb" -o "E:\binary"

# Open the guided setup explicitly
OpenEphysDataFormatConverter.exe --interactive

Options:

Option	Description
--from <format>	auto, binary, open-ephys, or nwb
--to <format>	binary, open-ephys, or nwb
--input, -i	Source file or directory
--output, -o	Destination file or directory
--overwrite, -f	Replace an existing destination
--interactive, -I	Open the guided setup
--help, -h	Show command help
--version, -v	Show the installed version

--from auto recognizes normal Binary recording directories, legacy Record Nodes, and .nwb, .h5, or .hdf5 files. For scripted pipelines, specifying --from explicitly is recommended.

Recognized data layouts

legacy Open Ephys Format

Record Node 101/
├── structure.openephys
├── 100_CH1.continuous
├── 100_CH1.timestamps
├── 100_CH2.continuous
├── 100_CH2.timestamps
├── 100_ADC1.events
├── settings.xml          (optional)
└── messages.events       (optional)

Open Ephys Binary Format

recording1/
├── structure.oebin
├── continuous/
│   └── <stream>/
│       ├── continuous.dat
│       ├── sample_numbers.npy
│       └── timestamps.npy
└── events/
    └── <event-stream>/TTL/
        ├── states.npy
        ├── sample_numbers.npy
        ├── timestamps.npy
        └── full_words.npy

NWB 2.x / HDF5

recording.nwb
└── acquisition/
    ├── <ElectricalSeries>/data
    ├── <ElectricalSeries>/timestamps
    ├── <ElectricalSeries>/sync
    └── <stream>.TTL/

The NWB reader targets Open Ephys-style ElectricalSeries and TTL TimeSeries objects. See the NWB format documentation for the Open Ephys GUI layout.

Data coverage

Data	Status	Notes
Continuous signals	Supported	Signed 16-bit samples; Binary data are sample-major and channel-interleaved
Sample numbers	Supported	Preserved when present; regenerated when required by the destination
Timestamps	Supported	Preserved or reconstructed from sample numbers and sample rate
Channel metadata	Supported	Names, sample rate, source-node metadata, and bit_volts/conversion values
TTL events	Supported	States, sample numbers, timestamps, and full TTL words where available
structure.oebin	Generated	Created for Binary output
legacy .spikes	Not supported	Spike waveform files are not converted
Message events	Partial	See Known limitations

Performance and safety

• Input safety: source files are opened read-only. Converted data are written to a separate destination.
• Large recordings: legacy Open Ephys ↔ Binary continuous conversion uses bounded streaming I/O and is intended for recordings of tens of gigabytes or more, subject to disk capacity and throughput.
• NWB memory use: the current pure-Go HDF5 writer materializes each continuous dataset. Binary → NWB is limited to approximately 1.5 GiB per continuous dataset.
• Existing output: the CLI refuses to replace an existing destination unless --overwrite is supplied. The guided setup asks for confirmation.
• Interrupted jobs: a failed or cancelled conversion can leave an incomplete destination. Inspect or remove that destination before retrying with --overwrite.

Known limitations

• Release executables are currently provided for Windows x64 only.
• Legacy .spikes files are not converted.
• messages.events may be retained as legacy_messages.events in the legacy → Binary batch output, but it is not translated into Binary MessageCenter arrays or NWB annotations.
• NWB messages and unrecognized processing objects are not copied to Binary or legacy output.
• Legacy ↔ NWB expects one Record Node/recording per NWB file. Split multi-recording inputs into separate jobs.
• Customized or very old legacy XML/header variants may require additional compatibility work.
• Structural validation does not establish scientific equivalence. Verify channel order, scaling, timestamps, event polarity, sample counts, and downstream reader behavior before using converted data for analysis.

Build and test

Building from source requires Go 1.25 or newer:

go test ./...
go vet ./...
go build -trimpath -ldflags="-s -w" -o OpenEphysDataFormatConverter.exe .

On Windows, build_windows.bat performs the release-style x64 build with CGO_ENABLED=0.

Project documentation

• CHANGELOG.md — user-visible changes in each release
• CONTRIBUTING.md — development and contribution workflow
• SECURITY.md — vulnerability reporting and sensitive-data guidance
• CITATION.cff — citation metadata for research use

Questions and reproducible bug reports can be submitted through GitHub Issues.

License and disclaimer

Released under the MIT License. This is research software provided without warranty. Keep an untouched copy of every raw recording and validate converted output with the quality-control procedures appropriate for your experiment.