The Yamaha Mobile Music Sequencer (MMS) uses two file types for user data: project files with the “yms1” extension and phrase files with the “yms2” extension. These files are accessible through either iCloud and/or iTunes file sharing. This note tersely describes the phrase file format.
A yms2 file is an Apple binary property list (plist) file. A property list file contains a collection of KEY:VALUE pairs. Pairs are organized and accessed using a dictionary structure. Both simple (e.g., integer, real) and complicated types (e.g., nested dictionaries, arrays) are supported.
The yms2 file format has its own keys that are unique to MMS. The challenge, of course, is to identify the keys and the allowed or specific values that may be associated with the keys. MMS key names begin with the “CODE_KEY_” prefix. Some values have a simple type. For example, values associated with CODE_KEY_PROGRAM are the integer type. Other values may be quite complicated. For example, MIDI data is stored as a binary array under the key CODE_KEY_SMF_DATA. In fact, the MIDI data is the raw binary for a Type 0 Standard MIDI File (SMF)!
Tools
Fortunately, Apple provides a utility for printing and converting property list files. This utility is called “plutil.” plutil is part of the Xcode developer package. On Windows, plutil is installed with iTunes and Apple Internet services. On Windows, plutil is installed into:
C:\Program Files (x86)\Common Files\Apple\Apple Application Support\
The plutil -p option prints the content of a plist file. This is a quick way to examine the content of a binary plist file. plutil also converts between binary and XML:
plutil -convert xml1 -o file.xml file.plist
plutil -convert - o file.plist file.xml
Property list files were originally in XML form. Apple eventually switched to the binary form. Fortunately, plutil converts between the two formats giving us a way both to read the content of a binary plist file and to write a new plist file with our own changes and MIDI data.
In order to modify an MMS plist file, you must first convert it to XML. Once the file is in XML, you may change the properties and replace the MIDI data with your own musical phrase. XML encodes binary data in base64 format. Thus, you also need a base64 conversion program. Several such programs are readily available on the web. You must first encode your Type 0 Standard MIDI File into base64 text before you insert the text into the XML for the plist. If you wish, you can decode existing MIDI phrase data and convert it to SMF.
The MIDI file is Type 0, 480 clock pulses per quarter (PPQ) note. The MIDI file contains two metadata events:
Metadata event: Time signature (e.g., 4/4)
Metadata event: Tempo
The rest of the file should be NOTE ON/OFF and controller events.
Scripts
I wrote two simple scripts to generate MMS yms2 files. The first script “make_one.bat” converts an SMF to a yms2 file. Parameters are passed to the script via environment variables. The script makes a few simple changes in an XML template file which contains the bulk of an MMS plist. It replaces the phrase name and phrase length. It converts the SMF file to base64 and inserts the encoded SMF data into the XML template. The template is renamed to the target yms2 file name.
@echo OFF set MIDI_FILE=%PHRASE_NAME%.mid set YMS2_FILE=%PHRASE_NAME%.yms2 del temp.b64 temp.xml copy %TEMPLATE% temp.xml base64 -e "%MIDI_FILE%" temp.b64 sed -i "s/NEW_PHRASE_NAME/%PHRASE_NAME%/g" temp.xml sed -i "s/NEW_PHRASE_LENGTH/%PHRASE_LENGTH%/g" temp.xml sed -i "// r temp.b64" temp.xml "C:\Program Files (x86)\Common Files\Apple\Apple Application Support\plutil.exe" -convert binary1 -o "%YMS2_FILE%" temp.xml
This script uses the “sed” stream editor to edit the template.
The second script “make_all.bat” sets the environment variables and converts each of the SMFs to an MMS yms2 file.
set TEMPLATE=template_drum.xml set PHRASE_LENGTH=16 set PHRASE_NAME=JFunk Dr1 A call make_one.bat set PHRASE_NAME=JFunk Dr1 B call make_one.bat set PHRASE_LENGTH=4 set PHRASE_NAME=JFunk Dr1 FA call make_one.bat set PHRASE_NAME=JFunk Dr1 FB call make_one.bat set TEMPLATE=template_bass.xml set PHRASE_LENGTH=16 set PHRASE_NAME=JFunk Bs A call make_one.bat set PHRASE_NAME=JFunk Bs B call make_one.bat
Keys
Here are the known keys in an MMS property list file. MMS does not generate a KEY:VALUE pair for properties having the default value for the key. Explicitly specifying the default value is acceptable. Be careful to use the correct data type and key names. If you use the wrong data type for a key, MMS will crash when reading the property list file. This happens when MMS tries to update its internal database of phrases and is a real pain to work around. If MMS crashes after you make a change, immediately remove the offending file and fix it.
Key Default --------------------------- ------- CODE_KEY_CHORD_SOURCE_TYPE 1 (M) CODE_KEY_CHORD_SOURCE_ROOT 0 (C) CODE_KEY_PLAY_MODE 0 CODE_KEY_TRANSPOSE 0 CODE_KEY_PHRASE_LENGTH: 16 CODE_KEY_BANKMSB 0 CODE_KEY_IS_VALID_ CODE_KEY_CHORD_SOURCE_TYPE CODE_KEY_PROGRAM CODE_KEY_CHORD_TYPE CODE_KEY_FILE_PATH CODE_KEY_CATEGORY 0 CODE_KEY_REMIX_POSITION CODE_KEY_PHRASE_VERSION CODE_KEY_SMF_DATA CODE_KEY_PHRASE_NAME CODE_KEY_REMIX2_POSITION CODE_KEY_LOLIMIT CODE_KEY_HILIMIT CODE_KEY_HIKEY CODE_KEY_CHORD_RETRIGG 0
The rest of this note describes the individual keys with respect to their counterparts in the user interface. They pertain to the phrase properties which you edit in MMS.
OTHER tab properties
These are the properties on the OTHER tab in MMS. Here is a table with some example KEY:VALUE pairs.
CODE_KEY_
Play --------------------------------------------
Category Len Trans Type CATEGORY PHRASE_LENGTH TRANSPOSE PLAY_MODE
----------------- --- ----- ---- -------- ------------- --------- ---------
Drum - Rock/Pop 4 0 LOOP
Drum - Dance 4 0 LOOP 1
Drum - Electronic 4 0 LOOP 2
Drum - HipHop 4 0 LOOP 3
Drum - Jazz 4 0 LOOP 5
Drum - Jazz 2 1 LOOP 5 8 1
Drum - Jazz 1 2 ONESHOT 5 4 2 1
CODE_KEY_CATEGORY is not generated for “Drum Rock/Pop” as this is default category with the internal value 0. The category number is same as the order in CATEGORY drop-down list on the user interface (UI) tab.
Phrase length is the number of measures multipled by beats per measure.
Time signature Phrase length CODE_KEY_PHRASE_LENGTH -------------- ------------- ---------------------- 3/4 1 3 3/4 2 6 3/4 3 9 3/4 4 12
Voice Link is a project property, not a phrase property.
CODE_KEY_PROGRAM is the key for MIDI instrument program number in Voice Link mode. Program change numbers start from zero. Some General MIDI instrument tables start from one. Beware! If you choose an instrument which is not in the MMS sound set, MMS displays a blank for the instrument name and the part does not sound.
Drum phrases generate CODE_KEY_BANKMSB=127 to select a drum kit in Voice Link mode.
Transposition is not as simple as changing the CODE_KEY_TRANSPOSE property. This aspect of the plist format is still a mystery. Transpose seems to affect the plist structure.
Category CODE_KEY_CATEGORY ------------------- ----------------- Drum - Rock/Pop 0 Drum - Dance 1 Drum - Electronic 2 Drum - HipHop 3 Drum - Jazz 5 Bass - Electronic 8 Bass - HipHop 9 Chord - Electronic 14 Pad - Electronic 20 Phrase - Electronic 26
CHORD properties
The chord properties below belong to the CHORD tab in MMS. Here is a table of example KEY:VALUE pairs.
CODE_KEY_
-------------------------------------------------
Category Len Note Root PHRASE_LENGTH CHORD_SOURCE_ROOT CHORD_SOURCE_TYPE
------------- --- ---- ---- ------------- ----------------- -----------------
Bass - HipHop 4 C CM
Bass - HipHop 8 C CM 32
Bass - HipHop 6 D DM 24 2
Bass - HipHop 7 E EM 28 4
Bass - HipHop 7 A AM 28 9
Bass - HipHop 5 B BM 20 11
Bass - HipHop 4 D DM7 2 2
Bass - HipHop 4 D Dsus2 2 33
Bass - HipHop 4 D Dsus4 2 32
The value for category (CODE_KEY_CATEGORY) “Bass – Hip Hop” is 9.
The chord type (CODE_KEY_CHORD_TYPE) is the note transposition table (NTT). The note transposition type for bass is usually “Bass” with value 4. The program change number (CODE_KEY_PROGRAM) for the bass in this case is 32, Acoustic Bass.
The chord source consists of the root note (CODE_KEY_CHORD_SOURCE_ROOT) and the the chord source type (CODE_KEY_CHORD_SOURCE_TYPE). Here is a table of some typical values.
CODE_KEY_
-----------------------------------
Category Len Root Type CHORD_SOURCE_ROOT CHORD_SOURCE_TYPE
------------- --- ---- ---- ----------------- -----------------
Chord - Elect 4 C CM 0
Chord - Elect 4 C CM7 0 2
Chord - Elect 4 C C7 0 19
Chord - Elect 4 C Ccc 0 34
Chord - Elect 4 C Csus2 0 33
Chord - Elect 4 C Csus4 0 32
Chord - Elect 4 C CM9 0 5
The chord source type follows an entirely different mapping than the physical
layout of the buttons on the screen!
CODE_KEY_CHORD_RETRIGG is 1 when this CHORD feature is enabled.
The tables below list values for the many chord-related keys.
CODE_KEY_CHORD_SOURCE_TYPE (35 types) --------------------------------------- 0 Major triad 18 dim7 1 M6 19 7 2 M7 20 7sus4 3 M7(#11) 21 7b5 4 Madd9 22 7(9) 5 7(9) 23 7(#11) 6 6(9) 24 7(13) 7 aug 25 7(b9) 8 m 26 7(b13) 9 m6 27 7(#9) 10 m7 28 M7aug 11 m7b5 29 7aug 12 m(9) 30 1+8 13 m7(9) 31 1+5 14 m7(11) 32 sus4 15 mM7 33 sus2 16 mM7(9) 34 cc 17 dim
CODE_KEY_CHORD_TYPE ------------------- 0 Melody 1 1 Melody 2 2 Chord 1 3 Chord 2 4 Bass 5 Bypass 6 Para
CODE_KEY_CHORD_SOURCE_ROOT -------------------------- 0 C 1 C# 2 D 3 D# 4 E 5 F 6 F# 7 G 8 G# 9 A 10 A# 11 B
High key CODE_KEY_HIKEY -------- -------------- C 0 C# 1 D 2 D# 3 E 4 F 5 F# 6 G 7 G# 8 A 9 A# 10 B 11
CODE_KEY_CHORD_LOLIMIT
Key CODE_KEY_CHORD_HILIMIT
----- ----------------------
G8 127
F#8 124
F8 125
E8 124
...
E2 52
D#2 51
D2 50
C#2 49
C2 48
...
A0 33
G#0 32
G0 31
F#0 30
F0 29
E0 28
...
C-1 12
B-2 11
A#-2 10
A-2 9
G#-2 8
G-2 7
F#-2 6
F-2 5
E-2 4
D#-2 3
D-2 2
C#-2 1
C-2 0