OTRN (Open Timecode-Related Notes)

1. Introduction

The .OTRN format was created to provide a universal way of exchanging timecode-related notes and markers for media files. It is particularly useful for film and audio editing, visual effects, and other post-production workflows. The intention is to create a simple format that is both human- and machine-readable, covers all the important attributes of such a file, and is easy to implement in any language for web and standalone applications. It should also resolve common issues with other formats, such as CSV, XML and OTIO.

Definition of a Note: A note is defined as a comment, annotation, marker, subtitle, or message associated with a specific timecode or a timecode range. Each note can have one or more replies and tags.

We provide various resources to help you understand the format more quickly and thoroughly.

The project and format have been released under the MIT licence as part of an initiative from EditingTools.io. We invite anyone to incorporate the format into their software to enable easy sharing of notes with other applications.

2. Use Cases

OTRN integrates the processes and platforms of reviewing and taking notes with those of video and audio post-production. This format has a variety of use cases.

• Post-Production Feedback: A client reviews a video or audio file and adds frame-accurate comments, such as "Cut here" or "Color is off." The editor imports the OTRN file, which instantly places all notes as timeline markers.
• Live Event Logging: During a concert, documentary shoot, game show, sporting event, reality TV show, or live-on-tape recording, a logger quickly notes or tags key moments ("Goal," "Highlight," etc.) with timecodes to create a highlight reel later.
• Protocols of meetings and calls: Notes can be taken during a meeting and reviewed later.
• Network Tests: Testing can be recorded and reviewed later more quickly.
• Caption/Subtitle Creation: Notes can be taken to be used as help reference for later captioning of the recorded content.

3. Supporting Apps

Applications that already support .otrn format.

Icon	App	Platform	Category	Description
	OTRN Editor	macOS	Developer Tool	Basic editor to create, edit or preview simple OTRN files.
	Live Timecode Notes	iOS/macOS	Logging	App for note taking with real-time timecode and collaboration features. Specifically designed for shows, events, streams and live-on-tape productions.
	Video Timecode Notes	macOS	Review Tool	A tool designed to review local stored video files and create timecode-related notes and markers.
	Marker Tool & Converter (iOS/macOS)	iOS/macOS	Converter	Standalone offline tool to convert and modify different marker formats.
	Marker Converter in next update	Web	Converter	Free online tool to convert and modify different marker formats.
	EDL Tool & Converter (iOS/macOS)	iOS/macOS	Converter	Standalone offline tool to convert and modify EDL files.
#	Plugin for Premiere Pro announced	Windows/macOS	NLE	Free Plugin/Extension to import and export OTRN files in older Premiere Pro versions 2022, 2023, 2024, 2025.
#	Extension for DaVinci Resolve announced	Windows/macOS/Linux	NLE	Free Plugin/Extension to import and export OTRN files in older versions of DaVinci Resolve.

Potential Supporters

4. OTRN Format Structure

The Open Timecode-Related Notes (.OTRN) format uses a standardized JSON structure. It is organized into three primary sections. The first (optional) section is a metadata object that defines basic information about the file and its origin. The second section is a sequence object containing the notes array with all the time-stamped notes. The third, optional primary section is a files array that allows users to attach additional notes to files and clips outside the sequence range.

Root Structure

{
  "metadata":
  	{
  	  /* Basic metadata about the file */
  	},
  "sequence":                   
	{
	  /* Definition of the sequence */
	  "notes": [
	    {
	      /* Notes, markers and replies */
	    }
	  ]
	},
  "files": [
  	{
	   /* Optional files array for clip notes */
	}
  
  ]
}

5. Metadata Object Definition

The metadata object contains optional informations about the file and where it comes from.

OTRN uses attributes written in Camel Case for readability.

An example with all attributes.

{
	"metadata": {
		"project": "The Dark Night",
		"fileName": "Episode_23_edit01.mp4",
		"fileUrl": "https://editingtools.io/project/thedarknight/Episode_23_edit01.mp4",
		"software": "Live Timecode Notes",
		"otrnVersion": 1,
		"otrnInfo": "This is an OTRN (Open Timecode-Related Notes) notes file. Learn more about the specification on https://otrn.editingtools.io",
		"timestamp": "2025-11-15T11:56:00Z"
	},
	/* other objects below... */
}


                    

6. Sequence Object Definition

The sequence object contains metadata necessary to correctly interpret the timecodes and the notes array.

An example with all attributes.

{
	"metadata":{
		/* metadata object */
	},
	"sequence": {
	    "name": "Final_Edit_V03",
	    "frameRate": 23.976,
	    "dropFrame": false,
	    "startTime": 0.0,
	    "startTimecode": "01:00:00:00",
	    "startFrame": 0,
	    "notes": []
	}
}


                    

7. Note Object Definition

The notes array contains a list of individual note objects. Each note is a comprehensive entry detailing the comment, its position, and its status.

Here is an example using the most commonly used attributes:

{
	"metadata":{
		/* metadata object */
	},
	"sequence": {
	    "name": "another_video_edit01",
	    "frameRate": 25.0,
	    "dropFrame": false,
	    "startTime": 0.0,
	    "startTimecode": "10:00:00:00",
	    "notes": [
	    	{
	    	"time": 61.0
	    	"timecode": "10:01:01:00",
	    	"comment": "The transition effect here feels a little too abrupt."
	    	"commenter": "Jane Doe",
	    	"timestamp": "2025-11-13T11:00:10Z"
	    	},
	    	{
	    	"time": 63.0
	    	"timecode": "10:01:03:00",
	    	"comment": "Change this picture."
	    	"commenter": "Jane Doe",
	    	"timestamp": "2025-11-13T11:01:18Z"
	    	}
	    ]
	}
}

Range Marker
There are additional attributes to define a range marker/note, also known as a spanned marker. It can be used to mark a longer scene or take for example.

Here is an example using a timecode range:

{
	"metadata":{
		/* metadata object */
	},
	"sequence": {
	    /* sequence data */
	    "notes": [
	    	{
	    	"time": 61.0
	    	"timecode": "10:01:01:00",
	    	"comment": "The transition effect here feels a little too abrupt."
	    	"commenter": "Jane Doe",
	    	"timestamp": "2025-11-13T11:00:10Z",
	    	"range": true,
	    	"timeOut": 63.0,
	    	"timecodeOut": "10:01:03:00"
	    	}
	    ]
	}
}

Replies & Tags
The following arrays can be added to a note to add replies and tags.

8. Reply Object Definition

The replies array within a note contains simple objects detailing responses to the main note. Replies are designed to be lean, as the main note holds the structural metadata.

Example: Reply structure usually happens below a comment and is often used in collaboration review tools.

Example Code:

{
	"metadata":{
		/* metadata object */
	},
	"sequence": {
	    /* sequence data */
	    "notes": [
	    	{
	    	"time": 61.0
	    	"timecode": "10:01:01:00",
	    	"comment": "The transition effect here feels a little too abrupt."
	    	"commenter": "Jane Doe",
	    	"timestamp": "2025-11-13T11:00:10Z",
	    	"replies": [
	    		{
	    			"commenter": "Sam K.",
	    			"comment": "Good catch, Jane.",
	    			"timestamp": "2025-11-13T11:31:00Z"
	    		
	    		},{
	    			"commenter": "Mark T.",
	    			"comment": "I was also thinking the sound design should reflect this change.",
	    			"timestamp": "2025-11-13T11:3:21Z"
	    		
	    		}
	    	
	    		]
	    	
	    	}
	    
	    ]
	}
}

9. Tag Object Definition

The tags array within a note contains simple objects that detail the tags associated with the main note. Some logger application, archives, and video review platforms use tags to make searching notes easier. Tags extend the note object.

Example Code for Tags within a Note:

{
	"metadata":{
		/* metadata object */
	},
	"sequence": {
	    /* sequence data */
	    "notes": [
	    	{
	    	"time": 120.5
	    	"timecode": "10:02:00:12",
	    	"comment": "This is a key interview quote that should be flagged for archival.",
	    	"commenter": "Mark T.",
	    	"timestamp": "2025-11-14T09:00:00Z",
	    	"tags": [
	    		{
	    			"name": "Key Quote",
	    		},{
	    			"name": "Archival Footage",
	    			"tagId": "archive_ftg",
	    			"group": "Material"
	    		
	    		}
	    	
	    		]
	    	
	    	}
	    
	    ]
	}
}

10. File Object Definition

In addition to notes in a sequence, some programs use file notes/marker in addition. The files array can be added to implement file specific notes.

The notes array and note object is identical to the note object in the sequence.

Example Code: File Object with Clip Notes

{
	"metadata": {
		"project": "File Note Demo"
	},
	"sequence": {
	    "name": "Main Sequence",
	    "notes": [] 
	},
    "files": [
        {
            "fileName": "SHOT_001_A003_C005.mov",
            "filePath": "/Volumes/projectmedia/rushes/SHOT_001_A003_C005.mov",
            "clipName": "Interview Take 5",
            "frameRate": 25.0,
            "startTime": 0,
            "startTimecode": "14:24:10:00",
            "notes": [
                {
                    "time": 10.0,
                    "timecode": "14:24:20:00",
                    "comment": "Camera operator mentioned this take has a minor lens flare issue.",
                    "commenter": "Data Manager"
                },
                {
                    "time": 55.5,
                    "timecode": "14:25:05:12",
                    "comment": "Best moment of the interview - very emotional.",
                    "color": "green"
                }
            ]
        }
    ]
}

11. Color Definition

Most applications support 8, 16, or 32 colors for notes and markers. Some applications use hex or rgb codes to define colors. OTRN uses color names instead of hex codes, because different software uses different color schemes to display note and marker colors. In order to make it possible to use color-coded notes across different platforms and software, color names are used to define the colors instead of a hex code.

When importing a file with more colors than the software supports, it should either change the colors to a base color that's close, or apply a default color.

When exporting notes from a software that works only with hex or rgb codes, the nearest color should be chosen to be added into an OTRN file. See more examples bellow.

Applications with only eight colors may need to consolidate the 32 possible colors into eight. Below is one example of how this could be done.

HEX to Color Name Resolver

Enter any hex color code (e.g., `#856545`) to find its closest match from the OTRN list of named colors.

12. Complete Examples

Minimal .otrn

The simplest example has only the basic elements required. It could be used for simple podcasts or audio file logging, for example.

{
  "metadata" : {
  },
  "sequence" : {
    "notes" : [
      {
        "comment" : "The crossfade at the end of the scene feels too abrupt. Can we extend the music cue by 1.5 seconds?",
        "time" : 462.0
      },
      {
        "comment" : "The sky replacement in this shot is looking too green compared to the previous scene. Needs to match 'Look B' better.",
        "time" : 610.0
      }
    ]
  }
}

Recommended Minimal .otrn

Some metadata should be added. Also information about framerate and timecode should be provided if the application provides it (e.g., for logging on videos).

{
  "metadata": {
	"project": "My Film project",
	"software": "Live Timecode Notes",
	"otrnVersion": 1,
	"otrnInfo": "This is an OTRN (Open Timecode-Related Notes) notes file. Learn more about the specification on https://otrn.editingtools.io",
	"timestamp": "2025-11-15T11:56:00Z"	
  },
  "sequence": {
	  "framerate": 23.976,
	  "dropFrame": false,
	  "notes": [
	    {
	      "time": 462.333,
	      "timecode": "10:05:42:08",
	      "comment": "The crossfade at the end of the scene feels too abrupt. Can we extend the music cue by 1.5 seconds?"
	    },
	    {
	      "time": 610.625,
	      "timecode": "10:08:10:15",
	      "comment": "The sky replacement in this shot is looking too green compared to the previous scene. Needs to match 'Look B' better."
	    }
	  ]
	}
}

Standard .otrn

Here is an example of an OTRN file with most of its attributes.

{
"metadata": {
	"project": "My Film Project",
	"fileName": "MyFilm.mp4",
	"fileUrl": "https://editingtools.io/project/myfilm/MyFilm.mp4",
	"software": "Live Timecode Notes",
	"otrnVersion": 1,
	"otrnInfo": "This is an OTRN (Open Timecode-Related Notes) notes file. Learn more about the specification on https://otrn.editingtools.io",
	"timestamp": "2025-11-15T11:56:00Z"
},
"sequence": {
	  "frameRate": 23.976,
	  "dropFrame": false,
	  "startTime": 0.0,
	  "startTimecode": "10:00:00:00",
	  "notes": [
	    {
	      "timecode": "10:05:42:08",
	      "time": 462.333,
	      "commenter": "editor_alice",
	      "name": "Music Edit Fix",
	      "comment": "The crossfade at the end of the scene feels too abrupt. Can we extend the music cue by 1.5 seconds?",
	      "color": "red",
	      "category": "Audio Mix",
	      "completed": false,
	      "replies": [
	        {
	          "commenter": "audio_bob",
	          "comment": "Got it. Will adjust the pre-lap and soften the cut. Thanks!",
	          "timestamp": "2025-11-12T10:05:00Z"
	        }
	      ]
	    },
	    {
	      "timecode": "10:08:10:15",
	      "time": 610.625,
	      "commenter": "director_charlie",
	      "name": "Color Grade - Look B",
	      "comment": "The sky replacement in this shot is looking too green compared to the previous scene. Needs to match 'Look B' better.",
	      "color": "blue",
	      "category": "Color Correction",
	      "completed": true
	    }
	  ]
	}
}

13. Example Files

14. Python

We have a Python library for OTRN, as well as example code for reading and writing.

Download: example-python-writer-reader.zip

What's Inside & How to Use It

The example-python-writer-reader.zip provides a complete, runnable demonstration of OTRN integration in Python. It's designed to show you exactly how to transform data into the OTRN format and how to safely read it back.

The ZIP contains three Python files:

1. otrn_lib.py: This is the core library. It holds all the necessary Python dataclasses (like OTRNDocument, Note, and Tag) and the two primary functions, read_otrn() and write_otrn().
2. example_writer.py: This script demonstrates how to construct a complex OTRNDocument object in memory and then uses write_otrn() to save it as a JSON file named example_data_to_read.otrn.
3. example_reader.py: This script shows how to load the OTRN file using read_otrn() and then iterate through the nested data structure to print all the notes and metadata.

Quick Start

1. Extract all three files into a single, dedicated directory.
2. Run the writer first to create the OTRN data file:
   python writer_example.py
3. Run the reader to load notes from the OTRN file:
   python reader_example.py

15. Swift

We provide a full Swift Package for OTRN, allowing you to easily read and write OTRN files in iOS, macOS, and command-line applications using native Swift Codable structs.

Download Examples + Package: example-swift-writer-reader.zip

Download Package: OtrnLibrary.zip

What's Inside & How to Use It

The example-swift-writer-reader.zip provides a complete, runnable demonstration of OTRN integration designed for a Swift Package or Xcode Command Line Tool project.

The ZIP contains the core library and a test XCODE project with multiple files:

1. Example OTRN Cli.xcodeproj: Demo Project for Xcode.
2. OtrnLibrary.swift: This is the core library file. It contains all the necessary public Swift structs (like OTRNDocument, Note, and Tag) which conform to Codable, along with the file I/O utilities read(from:) and write(to:).
3. write_example_simple.swift: Demonstrates how to write a minimal OTRN file using only required attributes.
4. write_example_advanced.swift: Shows how to **construct a complex OTRNDocument** object by setting all available optional properties, including nested Reply and File objects.
5. read_example.swift: Shows how to **load an OTRN file** using OTRNDocument.read(from:) and how to safely access and print all nested note details.
6. main.swift: This is the execution entry point. It calls the write and read functions sequentially to run the full demonstration.

Quick Start

Open the Xcode project Example OTRN Cli.xcodeproj and start it. It will create a write and read a test file and show the results in command line.

1. Extract all files.
2. Build and Run the main target. The main.swift file will automatically handle the workflow.
3. The script will create two demo files in your system's temporary directory and then read the advanced file back to print all its details to the console.

Implement the OTRN Package into an existing project

If you have an existing project, you can add the OtrnLibrary Package to your app.

1. Download the example-swift-writer-reader.zip
2. Open your Xcode project.
3. Right Click in Project navigator, choose Add Package Dependencies.
4. Click the button Add local... (at the bottom of the window) and select the OtrnLibrarym Package.
5. Add import OtrnLibrary to every Swift file in your app, where you want to access the library.
6. Copy and modify the needed code from read_example.swift or write_example... into your app.

16. Javascript

We provide a Javascript Package for OTRN, allowing you to easily read and write OTRN files within the browser or javascript applications.

Download Examples + Package: examples-javascript-writer-reader.zip

The examples-javascript-writer-reader.zip provides 3 runnable demonstrations of OTRN integration designed for Javascript (and HTML).

17. PHP

Examples for PHP integration coming soon.

18. OTRN Editor

A simple editor to create, open or edit simple OTRN files is available for macOS. The code is open source and everyone is invited to improve it.

Download (Version 0.4)

Download OTRN Editor from the AppStore.

The full source code will be available soon on Github for collaboration.

The Editor can currently not display Replies and Tags along some other attributes.

19. OTRN File Validator

Coming soon.

20. OTRN File Converter

Coming soon.

21. Latest Updates

Nov. 2025: Release of first version of OTRN

22. Help & Support

Contact [email protected] for any questions or cooperation requests.

23. License

The MIT License (MIT)

Copyright (c) 2025 EditingTools.io

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software/file format and associated documentation files (the "Software"), to deal
in the Software/File format without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software/File Format, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.