Jokosher File Format

Jokosher project files (with extension .jokosher) are XML text gzipped to save space. Everything about the project, with the exception of the actual audio is stored in a .jokosher file.

XML Elements

Required children means exactly one (no more, no less) of each subelement must be present. Optional children means any number (including zero) of each subelement must be present.

• <JokosherProject> Contains the entire project (instance of the Project class).
  • Only one may exist in a file.
  • Required Children: <Parameters>, <Undo>, <Redo>
  • Optional Children: <Instrument>, <DeadInstrument>
  • Format is: <JokosherProject version="0.1">
    • Version attribute is a simple version string (ie "0.1").

• <Parameters> Stores all the class variables that need to be saved.
  • Only one may exist in a node (not including subnodes).
  • Format of children is <variableName type="variableType" value="variableValue"/>
    • variableName is the name as it would be typed in the code.
    • variableType can be one of bool, int, float, str.
    • variableValue is the string representation of the variables value.

• <Undo> Stores all the commands in the undo stack.
  • Only one may exist in a project file.
  • Format of children is <Command value="commandString"/>
    • commandString is the command using Jokosher's CommandLanguage, used by Project.ExecuteCommand()

• <Redo> Stores all the commands in the redo stack.
  • Only one may exist in a project file.
  • Structure is the same as the <Undo> element.

• <Instrument> Contains an instance of the Instrument class.
  • Unlimited number can exist in a project.
  • Required Children: <Parameters>
  • Optional Children: <Event>, <DeadEvent>
  • Format is <Instrument id="uniqueID">
    • uniqueID is an integer different from every other instruments' and events' ID.

• <DeadInstrument> Contains an inactive instance of the Instrument class. These objects are kept only for undo compatibility.
  • Unlimited number can exist in a project.
  • Structure is the same as the <Instrument> element.

• <Event> Contains an instance of the Event class.
  • Unlimited number can exist in a project.
  • Required Children: <Parameters>, <FadePoints>, <Levels>
  • Format is <Event id="uniqueID">
    • uniqueID is an integer different from every other instruments' and events' ID.

• <DeadEvent>Contains an inactive instance of the Event class. These objects are kept only for undo compatibility.
  • Unlimited number can exist in a project.
  • Structure is the same as the <Event> element.

• <FadePoints> Contains all the volume points for any volume changes in an Event.
  • Only one may exist in an <Event> element.
  • Format of children is <FadePoint position="posFloat" fade="fadePercent"/>
    • position is a float of the position of the point in seconds starting at the beginning of the event.
    • fade is a 0-1 float of the percentage of the actual volume which will be outputted.

• <Levels> Contains cached levels from the Event's audio file.
  • Only one may exist in an <Event> element.
  • Format is <Levels value="commaDelimitedFloatString"/>
    • The element's value is a comma delimited list of strings representing floats.
    • The list will often include hundreds or thousands of floats for long audio files.

Inspect a Jokosher Project File

To inspect a .jokosher file, use:

gunzip -c my_project_file.jokosher | less

Example Jokosher Project File

<?xml version="1.0" ?>
<JokosherProject version="0.1">
        <Parameters>
                <name type="str" value="NewProject"/>
        </Parameters>
        <Undo>
                <Command value="P DeleteInstrument(1)"/>
        </Undo>
        <Redo>
		<Command value="P ResurrectInstrument(3)"/>
	</Redo>
        <Instrument id="1">
                <Parameters>
			<name type="str" value="Bass Guitar"/>
		</Parameters>
		<Event id="2">
			<Parameters>
				<name type="str" value="music.mp3"/>
			</Parameters>
			<FadePoints>
				<FadePoint fade="0.543" position="0.432224"/>
				<FadePoint fade="0.845634" position="4.32224"/>
				<FadePoint fade="0.2433498" position="11.2684"/>
				<FadePoint fade="0.99" position="15.34572"/>
			</FadePoints>
			<Levels value="0.0035400390625,0.00323486328125,0.0006103515625"/>
		</Event>
		<DeadEvent id="3">
			<Parameters>
				<name type="str" value="song.ogg"/>
			</Parameters>
			<FadePoints/>
			<Levels value="0.0035400390625,0.00323486328125,0.0006103515625"/>
		</DeadEvent>
	</Instrument>
	<DeadInstrument id="4">
		<Parameters>
			<name type="str" value="Electric Guitar"/>
		</Parameters>
		<Event id="5">
			<Parameters>
				<name type="str" value="audio.wav"/>
			</Parameters>
			<FadePoints/>
			<Levels value="0.0035400390625,0.00323486328125,0.0006103515625"/>
		</Event>
		<DeadEvent id="6">
			<Parameters>
				<name type="str" value="fireflytheme.wav"/>
			</Parameters>
			<FadePoints/>
			<Levels value="0.0035400390625,0.00323486328125,0.0006103515625"/>
		</DeadEvent>
	</DeadInstrument>
</JokosherProject>