The VidSyncDocument (.vsd) is the editable project record. Exported tables, images, and video clips are copies made for analysis, review, or presentation. Keep the .vsd file and its source videos after exporting so that measurements and project organization can be checked or revised later.
Before exporting
- Save the VidSyncDocument.
- Review Object and Event names, note codes, and annotations for spelling and consistent use.
- Check for unfinished points or Events and decide how they should appear in the exported data.
- Decide whether the analysis needs a simple table or the complete Object and Event hierarchy.
- Use filenames that identify the project and export date. Record the VidSync version and measurement units with the exported data when they are needed for later interpretation.
Exporting measurement and observation data
| Format | Contents and common use | Limitations |
|---|---|---|
| CSV | A flat table suited to spreadsheets and statistical programs. | Some hierarchy and relationships must be simplified to fit rows and columns. |
| XML | The complete Object and Event hierarchy, including many-to-many relationships, notes, annotations, video-clip information, and calibration details. | Requires software or a script that can read the XML structure. |
| Clipboard | Point measurements and connecting-line length or speed tables that can be pasted directly into a spreadsheet. | Intended for quick transfer of a particular table, not for preserving the whole project. |
CSV is usually the quickest route into a spreadsheet, R, Python, or another analysis program. Its rectangular structure cannot preserve every relationship in a VidSync project. For example, an Event associated with two fish Objects has a many-to-many relationship that may need to be flattened or repeated in CSV. Use XML when those relationships or the complete project organization must be retained.
XML is also the better choice when an importer needs annotations, notes, clip information, or calibration records along with measurements. A custom XML importer can convert the data into the tables required for a particular study while retaining the original hierarchy for reference.
Clipboard output is convenient for checking a small set of results or moving a displayed point, length, or speed table into a spreadsheet. Save the resulting spreadsheet explicitly. Clipboard contents are temporary and do not contain the full VidSync project.
Capturing still images and video clips
The Capture tab can save still images or sections of video with or without overlays.
Video capture without overlays can be fast because VidSync can copy the selected video segment. A capture with overlays must be rendered frame by frame and may take much longer. In the recorded tutorial, a 20-minute clip without overlays took only seconds on the computer used for the demonstration, while the same length with overlays could be left running overnight. Those times describe the 2015 system, but the difference in processing remains relevant. Export a short section first when estimating the time required for a long capture with overlays.
Record the clip, camera, start and end time, and whether overlays were included when a capture will be used as part of the scientific record. Check the captured file before deleting any temporary working copy.
Checking an export
- Open the exported file in the program that will be used for analysis.
- Compare Object, Event, and point counts with the VidSync project or with a small set of records whose expected contents are known.
- Check several timestamps, names, Event types, and note codes.
- Confirm the units and coordinate columns for spatial measurements, or the expected timing and category fields for event-logging projects.
- Check how incomplete points, blank notes, and Events involving more than one Object are represented.
- Keep the data dictionary, analysis code, exported files, VidSyncDocument, and source videos together or in documented archival locations.
Reading .vsd files directly
Advanced users can read VidSyncDocument (.vsd) files through SQLite. The database is managed by Apple’s Core Data and has a more complicated structure than the CSV or XML exports. Its schema should be treated as an implementation detail that may change between software versions. DB Browser for SQLite can be used for inspection, and scripts can query the database through SQLite libraries in Python or other languages.
As the developer of VidSync I have sometimes had occasion to read a .vsd file directly from another program, usually when testing some mathematical internals, but I don’t think this was common (if done at all) among users. However, as of 2026, frontier agentic AI models can navigate .vsd files seamlessly (especially when given the original VidSync manuscript or github repository link as context), and users with these models in their analytical workflow might fight that exporting through a special output format is no longer necessary. Just make sure your workflow is carefully validated.