CTM File Explanation

Files that have the .ctm extension are Citra movie files, used for storing input data. This input data can be used to perfectly recreate gameplay and is most commonly known to be used for the creation of Tool Assisted Speedruns (TAS). As far as I am aware there is no thorough explanation or notes on how .ctm files are structured other than in the source code for Citra in the directory citra/src/core/movie.cpp. Because of this, I have gone through and learned how the file format is structured using the source code and will explain my findings.

.ctm files always begin with a 256 byte header. I will be explaining the current canary version of .ctm files here as they are mostly the same besides storing some extra information. The header data is structured as follows:

1.) 0x00 -> Filetype identifier. These 4 bytes will always be 43 54 4D 1B. In ascii, this says "CTM 0x1B" to ensure that this is indeed
			a CTM file
2.) 0x04 -> ROM ID. These 8 bytes tell the movie file which game the movie file is associated with. This data is read in little endian
			meaning it is interpreted from right to left. The remaining header data will be in little endian. This data is also
			interpreted in hex.
3.) 0x0C -> Revision git hash. These 20 bytes show what version of Citra the movie was created with.
4.) 0x20 -> System clock init time. These 8 bytes show time at which the movie file was created. This time is determined by the 3DS
			clock setting.
5.) 0x28 -> Movie ID. These 8 are a unique ID generated for every movie. These ID help keep savestates separate for each movie file.
6.) 0x30 -> Movie author. These 32 bytes show the author of the movie as inputted during movie creation.
7.) 0x50 -> Record count. These 4 bytes show how many rerecords have been performed for this movie.
8.) 0x54 -> Input poll count. These 4 bytes show how many times Citra has pulled for button and circle pad inputs during the length of
			the movie. This count is how Citra keeps track of how long the movie is.
9.) 0x5C -> Padding. These 164 bytes are just used to get the header to 256 bytes. These should all be 00.

Here's an image to help visualize the structure: https://imgur.com/YtJnt3K.png

After the data associated with the header comes the actual input data for the movie starting at 0x100. Input data is unfortunately not stored in a format that is very easy to view or edit manually. Input data is stored in 7 byte chunks that are associated with the various controller states. These states are:
	00 -> PadAndCircle: The data associated with button and circle pad inputs
	01 -> Touch: Touchscreen inputs
	02 -> Accelerometer: Accelerometer data
	03 -> Gyroscope: Gyro data
	04 -> IrRst (debreciated???): Data associated with the the extra inputs for the circle pad pro (C Stick, ZL, ZR)
	05 -> ExtraHidResponse: Data associated with the the extra inputs for the New 3DS or circle pad pro (C Stick, ZL, ZR)

Each 7 byte chunk begins with 1 byte that specifies the controller state. For example, if the controller state is the touch screen, the data chunk will begin with 01. The following 6 bytes specify the actual input data such as where on the touch screen is being touched. The tricky part is that these data chunks are recorded as Citra is polling for the various types of information. Because all of these different controller states are not polled at the same rates, these data chunks are not in a consistent order. This also means that input data for any of the given controller states will be polled multiple times on any given frame. This makes syncing a movie very consistent based on my testing but makes hex editing very challenging. The various polling rates are as follows
	PadAndCircle = 234 ticks/second
	Touch = 234 ticks/second
	Accelerometer = 105 ticks/second
	Gyroscope = 101 ticks/second
	IrRst = ??? (I believe that movie files always use ExtraHidResponse instead of this)
	ExtraHidResponse = Different depending on the game

This image contains a diagram that explains how the data is structured for each controller state: https://imgur.com/cYfAU7w.png

I have created a template file that works with 010 Editor, a robust hex editor software, that helps to easily parse CTM files. More details here: https://github.com/benstephens56/Citra-Movie-File-Parser