Migrate: voyant_recording_migrate
Convert a pre-v1.0.0 recording to the current .vynt format.
Since v1.0.0, all Voyant tools and APIs read recordings in the native .vynt format. Recordings made with a pre-v1.0.0 release use an older format and must be converted once with this tool; the original file is left untouched. Tools older than v1.0.0 cannot read .vynt recordings — to work with new recordings, upgrade the tools.
The visualizer offers this same conversion automatically when you open a pre-v1.0.0 file. Use
voyant_recording_migratefor scripted or headless conversion.
Migrating scripts or code too? The v1.0.0 migration guide covers the tool renames and the Python/C++/CSV changes.
Use voyant_recording_migrate --help to see all available options.
Usage
voyant_recording_migrate --input my_recording.bin
By default the converted file is written next to the input with a .vynt extension (my_recording.bin → my_recording.vynt). If the input is a pre-v1.0.0 file that is already named .vynt, choose a different output explicitly:
voyant_recording_migrate --input old_recording.vynt --output old_recording.migrated.vynt
Options
--input <FILE>— pre-v1.0.0 recording to convert (required).--output <FILE>— output path; must end in.vynt(default: the input path with a.vyntextension).--no-verify— skip re-reading the output and comparing it point by point against the source. Verification is on by default.--force— overwrite the output file if it already exists. Without it, the tool refuses to replace an existing file. The input file is never overwritten.
The conversion is atomic: the output is staged as <output>.partial and only renamed into place after the write — and the verification pass — succeed, so a failed or interrupted run never leaves a bad file under the output name.
Expected Output
Migrating "my_recording.bin" -> "my_recording.vynt"...
Migrated 512 frames (8134656 points) to "my_recording.vynt"
Verified against the source: 512 frames, 8134656 points, max xyz deviation 4.750e-7 m
Legacy recordings carry no sensor or host state, so the converted file reports both as not recorded.
As the last line notes, the pre-v1.0.0 format stored no sensor or host state, so converted recordings report that state as absent. The measured point values are carried over as recorded: the deviation in the verification line is a round-trip check on the derived Cartesian coordinates, where floating-point rounding leaves a sub-micron difference. The one value the conversion cannot carry over is a point timestamp that was negative in the legacy file — the native field cannot represent it, so it is folded to 0 and the run reports how many points that affected.
How do I know a file needs converting?
Opening a pre-v1.0.0 recording with a v1.0.0+ tool or API fails with a message naming this tool and the exact command to run. In the visualizer, opening one brings up a Legacy Recording prompt offering to convert it for you.