An early peek at a technical exploration of the ProPresenter 7 file format (.pro)

N.B. This information is probably only of interest to developers – nothing here will be of any real use to “regular users” of ProPresenter.

 

TLDR: Pro6 documents are XML, Pro7 documents (and config files) are Google protocol buffers.  To read and write .pro files you will need a complete set of .proto files that describe all the possible messages that the .pro file might contain – if you have these .proto files Google makes it super easy to create code to read/write .pro files. I’ve started work on reverse engineering the messages and manually creating .proto files to eventually allow this.

 

I love computers – especially automation (making things happen automatically) and integration (making things works well together). I also love all aspects of working with ProPresenter including system design,  show setup and operating.

 

I was quite an excited nerd when I first noticed that the ProPresenter 6 document file format was human-readable XML that was somewhat “self-describing” so that it was easy to figure out what it all meant.

I could use my knowledge of computers, programming and scripting to work with ProPresenter documents directly and automate all sorts of otherwise laborious tasks, like that time I wanted to rename our standard arrangement names or even create utility applications like All-Caps for Windows or Volume editor for MacOS.

.pro6 files are an “easy to figure out”, human readable XML

I’m not the only one who has noticed that the .pro6 file format was human-readable XML and quite clear to figure out.
There are others I’ve seen posting in the Official FaceBook Users Group doing the same thing and making scripts and programs that automate their own workflows.

 

Naturally I was excited when Pro7 came out – I even joined the beta testers group. I have really enjoyed exploring all the wonderful new features right and was blown away by the performance and possibilities with the new Windows version!
However,  when I took a look inside the .pro document file format, I got a bit of a surprise!
They are no longer 100% human readable XML and instead seem to be some sort of mix of binary and plain text.

ProPresenter 7 .pro files seem to be a mix of binary and plain text

I can’t remember exactly how I figured it out, but I now know that
Pro7 documents (and configuration files) are actually Google Protocol Buffers written to file

 

What are Google protocol buffers?

Let me quote from Google to best summarise what protocol buffers actually are….

Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.

Also, here is a good introduction to how a developer uses protocol buffers….

You specify how you want the information you’re serializing to be structured by defining protocol buffer message types in .proto files. Each protocol buffer message is a small logical record of information, containing a series of name-value pairs

Once you’ve defined your messages, you run the protocol buffer compiler for your application’s language on your .proto file to generate data access classes. These provide simple accessors for each field (like name() and set_name()) as well as methods to serialize/parse the whole structure to/from raw bytes 

What this means for developers is that once they have their data structures defined in (human readable) .proto files, then the Google protocol buffer compiler will take that .proto file and automatically generate all the code you need to create your data structures, store them to file and later read them back from that same file – and this is what ProPresenter uses for it’s files.

It’s actually pretty cool that the Google protocol buffer compiler can take your .proto file and generate code for a number of popular languages.

Are there apps/tools to view Google protocol buffers?

What if I want to look inside the .pro files and understand what is stored in there?
There are a few apps/scripts I’ve found that can display the contents of a Google protocol buffer – however, it’s not as useful as I had hoped since the name of each data field is NOT stored in the protocol buffer – so these viewer applications can only show the hierarchy of data values without any naming!

Here is a look at a .pro file with a Python script and a MacOS app for viewing the data within protobuf files.

https://github.com/mildsunrise/protobuf-inspector
https://sourceforge.net/projects/protobufviewer/

Although the viewers can’t display the names of each field in the data structure (since they are not present in the data), it’s not too hard to start guessing what each data field is!
This is especially easier when you compare a .pro6 file with human readable XML to the resultant .pro file once it has been imported into Pro7. Combining that with a few other reverse engineering tricks, and I’ve been able to make a start of re-creating a working .proto for .pro presentation files.

It’s not much yet, but over the next few months, I hope to have figured out enough to read and write .pro files once again!
I’ll do a part 2 and include a GitHub repository!

syntax = "proto2";

message Presentation {
  enum Application {
    APPLICATION_UNDEFINED = 0;
    APPLICATION_PROPRESENTER = 1;
    APPLICATION_PVP = 2;
    APPLICATION_PROVIDEOSERVER = 3;
    APPLICATION_SCOREBOARD = 4;
  }
  
  enum Platform {
    PLATFORM_UNDEFINED = 0;
    PLATFORM_MACOS = 1;
    PLATFORM_WINDOWS = 2;
  }
 
  message PlatformVersion {
    required uint32 majorversion = 1;
    optional uint32 minorversion = 2;
    optional uint32 patchversion = 3;
    required string build = 4;
  } 
 
  message ApplicationVersion {
    required uint32 majorversion = 1;
	required uint32 minorversion = 2;
	required uint32 patchversion = 3;
	optional uint64 build = 4;
  }
  
  message ApplicationInfo {
    required Platform platform = 1;
    required PlatformVersion platformversion = 2;
	required Application application = 3;
	required ApplicationVersion applicationversion = 4;
  }

  message UUID {
    required string uuidstring = 1;
  }

  message Background {
    optional Color color = 1;
    optional Gradient gradient = 2;
    optional uint32 isenabled = 3;
  }
 
  message Color {
    required float red = 1;
    required float green = 2;
    required float blue = 3;
    required float alpha = 4;
  }

  enum GradientType {
    LINEAR = 0;
    RADIAL = 1;
    ANGLE = 2;
  }

  message Gradient {
    required GradientType gradienttype = 1;
    required uint32 angle = 2;
    required uint32 length = 3;
    required uint32 stops = 4;
  }
  
  message Arrangement {
    required string uuidstring = 1;
  }

  required ApplicationInfo applicationinfo = 1;
  required UUID uuid = 2;
  required string name = 3;
  optional Background background = 8;
  //optional Chordchart chordchart = 9;
  optional UUID selectedarrangement = 10;
  repeated Arrangement arrangements = 11; 
  
}

1 thought on “ProPresenter 7 – File Format, Part 1

  1. Nice work on figuring out the Pro7 file format!! Yes, finding ways to automate things will definitely be a big win. There’s always plenty of scope to automate things within the sphere of Church tech..!

Leave a Reply