Production Guide

From MMS Wiki
Jump to: navigation, search

Production tools

In addition to the MMS Production Tool, you will need some or all of the following:

Google Chrome (free). All MMS products are optimized for Google Chrome. You have no reason to use any other browser.[1]
MuseScore (free). Get our version here: Win: [2]. Mac: [3]. Our version has an important extra feature - Linearization.
Sibelius (not free, MMS has a licence)
PhotoScore or PhotoScore Lite which comes for free with the Sibelius license.
Finale (not free, MMS has a licence. Finale Notepad is free and does most of the things you need). [4]
Audacity (free). You will occasionally need to edit some audio files. [5]
Google account For MMS/PF and for accessing the metadata on Drive

Files and formats

For making a MatchMySound exercise following files are needed (everything that does not have the comment OPTIONAL is needed):

- The notation file. MMS graphics are based on MuseScore, and it can import MusicXML. So either .mscz or .xml files are welcome. We can work with Sibelius and Finale files (.sib and .mus) as well by converting them into MuseScore format via the XML export. Note! XML export rarely works perfectly, and many details will be lost or replaced.

- A PDF for reference (sometimes the XML import goes wrong, and then we need to see how the original looked like). Note! for pieces with Replaced graphics, we need a vector graphics PDFs (or other vector formats).

- Audio files:

1) for the reference track (has to be exactly what you expect the student to play, it's the basis of the comparison and feedback. Can be synthesized from the notation file)
2) for the demo track (if for some reason you don't want the students to hear the reference track). OPTIONAL
3) for the backing track (to let the students hear a band to earphones while playing). Note! The backing track must not include the reference track. OPTIONAL

All the audio files have to originate from the same mix, i.e. have the same tempo. The ends and beginnings do not have to be cut; equally, we'll sync them up. Supported audio file formats include .wav, .mp3, .ogg

- Youtube link of the video of the piece (either unlisted or public, not private) that has the same audio track as you want to use for the demo audio track. OPTIONAL

Exercise metadata

All MMS exercises have the following metadata fields (everything that does not have the comment OPTIONAL are needed):

1) Title. It's taken from the score file but can be edited anytime
2) Author. It's taken from the score file but can be edited anytime
3) Exercise description. OPTIONAL. It can be used for copyright, arranger etc. It can be set separately for each exercise or the whole collection
4) Instrument. Taken from the score file. When set to 'multiple' then the recording option disappears.
5) Default score goal. 80% by default. Can be changed later and set separately for each assignment
6) An exercise can also have an attachment (a PDF or other image).
7) Tempo. Taken from the score file but can be changed at the first stage of exercise production. Cannot be changed once the exercise is finalized.


The MMS exercises are organized into collections. All MMS collections have the following metadata fields:

1) Title. It's the only obligatory field.
2) Author
3) Instrument Use the help of autofill
4) Cover art
5) Type (method books, choral music, brass etc)
6) Series (Standard of Excellence, Absolute Beginners, A New Tune a Day, etc.)
7) Order. You can occasionally bring up some collections by writing a small number into this field (-99 for example). Don't forget to change it back or you will have to use even smaller numbers next time.
8) Collection description. It is important - here goes the main copy that is displayed next to the cover art in a list of collections
9) Exercise description. If all exercises in the collection need to have a certain piece of text such as copyright or the arranger, then this is the place. However, it has to be set before the exercises are created into this collection

Adding collections

Collections can be created and edited by a user who has the Collections role.

- One way of creating a new collection is by loading the URL /comp.html#/edit_collection/ At least title field has to be filled under the metadata tab. Don't forget to 'Save'.
- The other way is Cloning an existing collection (only metadata will be copied). Do it on the Edit Collection page.

Naming and publishing collections

If 'Publish this collection (ready)' is checked then it will show up under the set Collection package to the Consumer group that has the rights to see that package. New collections are automatically not included in any package. You'll have to go to /collections/packages to add the collection to an existing package or to create a new package. If you create a new package, then you will also need to add it to a consumer who is meant to have access to it. Do it at /collections/consumers

Cover art

The design works best with portrait oriented images. Do not upload big image files, 100 kb is enough.

Adding exercises to a collection

- Existing exercises can be added on the Edit Collection page's Actions menu. The exercise list in the drop-down includes exercises from the user's collections 'Favorite Exercises' and 'My Exercises'. It is a non-preferred use case.
- When creating an exercise through the MMS production tool, a collection can be chosen from the drop-down. It's the preferred use case but unavailable through the public exercise creation flow.


In the Actions menu on the Edit Collection page, one can add subdivisions. Those will appear at the bottom of the exercise list and can be dragged into the correct position (use scroll wheel and PgUp). Subdivisions have two functions: 1) they help to group the exercises and will divide content into two columns 2) they allow assigning the full content of a subdivision to students (for example, name it Lesson 1, drag appropriate exercises under that division and later assign the whole lesson at once). The subdivisions are designed to be added after exercises. To navigate the subtitles into their correct places, use left click+scroll (or PgUp, Home buttons).

- When creating an exercise through the MMS public exercise creation flow, the following URL can be used to automatically include the exercise into a collection /comp.html#/create_notes?to_collection=<collection id>

Converting files

From .mus to MusicXML - Use Finale's default Export to MusicXML tool or Finale Dolet plugin
From .sib to MusicXML - Use Sibelius's Export to MusicXML too
From XML to .mscz - Open directly in MuseScore
From Guitar Pro to .mscz - Open directly in Musescore (supported since .gp3)
From .pdf to .mscz - Use PhotoScore

Editing in MuseScore

Editorial principles
- Keep in mind the context of use (sufficient space for feedback)
- Does not have to be a clone of print music
- Moving and defining elements (select all, styles): Make sure all elements are designated and styled properly, do not use wrong styles (e.g. do not designate ritenuto as free text, make it dynamics). Same goes for placement - do not just drag elements around, use their default positions if possible.
- Export the parts before leaving MuseScore. (Inside MuseScore, the parts are called Excerpts. An excerpt can be a combination of parts).
- You cannot optimize for both page and scroll view, choose one (depends on the use case, when in doubt, make page view look good).

Ask the production team members for an up-to-date document called 'The MMS Production Guide Step 1: Working with MuseScore'. That file includes project specific guidelines.

Production tool how to use

Note! The MMS Production tool is separate from the public exercise creation flow. It can only be accessed by MatchMySound's own production team or the partners who specifically license that from us.

Step 1: Upload score file

The file should be previously checked in the same MuseScore version that we currently have on the server side (Usually the latest stable version). All parts have to be generated in local MuseScore and the same goes for line breaks and other visuals. Linearization has to be done in advance, too. Although MMS detects and separates the parts and tries to linearize the music, often the result is not sufficient.

Step 2: Audio files and parts

- Choose a collection. The collection has to be created in advance, see above.
- Upload audio files .ogg is the best since everything gets converted into .ogg anyway. Choose all needed audio files at once and make sure that their order is always the same (e.g. demo track, reference track, backing track) to avoid problems in next phases where file names cannot always be seen.
- Add Youtube video link (just the 8-10 last characters of the YT URL). The video must have exactly the same audio file that you plan to use as the reference track.
- Choose tempo for MIDI. It is taken from the MuseScore file, change it if you need. If you are using real audio files then make the MIDI tempo match the audio recording (loosely).
- Choose Full audio track. It is the track which will be accessible from all the individual parts. Different products may use it differently.
- Exercise parts configuration. Click on a part to open its settings and set the Name, Instrument (always choose from what the autocomplete suggests) Etalon (alias for the reference track), Audio (alias for the demo track), and the Backing track. Lastly, set the Score visual (can be any of the individual parts or the full score). Percussion track means that the Recording option will be turned off (use it for drums).
- If you don't need all the excerpts/parts, then you can delete some. It's also possible to add them back by clicking the '+Add new part' button below.
- If you are not using real audio files, you will see a button labelled 'Create MIDI only exercise'. If you are using at least one audio file, you need to proceed to the mapping phase (see next step).

Step 3: Map audio to score

The default view is 'Matching. Playback starts and stops by pressing space. For other keyboard bindings, click on the 'i' next to the page's title. The functions from left to right:

- InTempo. It distributes the bars evenly as if the music was played by a machine. Use it for very rhythmic audio files.
- BarBegs. Uses the matcher algorithm to auto-align the bars with the first notes of measures and leave the other bars to the InTempo mode.
- Matching. That mode uses the matcher algorithm to align all bars with the music as best as it can.
- ReMatch. Sometimes an audio file begins with non-musical sounds and it may confuse the matcher. In that case, move the first bar manually to the beginning of the music and run the ReMatch. The algorithm now excludes everything that sounds before the first bar.
- Save. Saves current mapping. When your browser closes and you upload the same MuseScore file again, then the mapping work done so far will be restored. There is also an autosave so that button is not very important anymore.
- Load. Restores the bars to the positions after saving. Works also when the browser has been restarted.
- Demo. Changes the playback file to demo audio.
- Ref. Changes the playback file to reference audio.
- Click. Changes the playback file to click track.
- Select. Allows selecting a section to run different matching options on different areas in music.
- Clear. Resets the selection. That button only appears when there is an active selection.
- Change mapping settings. Allows changing the audio files and visuals used in the mapping view.

Level of the accuracy of the alignment always depends on the context - if the reference track is real audio then it just has to look good. - Mapping done. Moves to the final step of the process.

Step 4: Align audio files

All included audio files will be displayed. The point here is that in the mapping step you aligned just one audio file with the score but an exercise may have more. If all the audio files originate of the same mix and have equal length, then you normally don't have to do anything in this step. If not, however, then the matching algorithm attempts to match the audio files to each other and if the result is not satisfying, then Ctrl+drag lets you change their positions in relation to each other. Buttons from left to right:

- Play. Starts playback. You can use spacebar from the keyboard instead.
- Pause. Stops playback. You can use the spacebar.
- Toggle switch next to a speaker icon. Mutes/unmutes an audio file.
- A bigger slider next to an audio graph. Allows adjusting the playback volume of an audio track.
- Cut. Cuts the part of an audio file after that comes after the playhead/cursor. That is useful when an audio track has something unwanted in it or is simply too long.
- Time marker that appears in the place of the 'Cut'. Shows where the cut was performed. Clicking on it removes the cut.
- Create new exercise. It finalizes the production process and opens the edit exercise dialogue.
- Replace exercise. Appears only when you are repairing an exercise. Sometimes you are actually not repairing it and just want to create a new one. Then you would use the 'Create new exercise' which leaves the old one in place. However, if an exercise is already in use, the recommendation is to replace it because this way its id remains the same and the existing assignments do not suffer.


Go to the Playback menu and listen to 'All audio tracks' as well as all the individual tracks and Metronome. Compare each audio file playback to the musical score and verify that they are perfectly synchronized. Keyboard shortcuts: 'r' plays the reference audio, 'a' plays all files, 'd' plays demo audio, and 'b' plays the backing track.

Advice on choosing the audio files

- Backing track. The rule of thumb is that it must not contain the reference track. If this is not possible then there will be no backing track at all. Most users never hear that track because they either don't hit 'Record' and are just browsing or they use the other recording options.

- Reference track (internally called 'etalon'). Best if we have a real instrument track from the publisher. If not then it is worth checking if the existing audio tracks have panned the material into separate stereo channels. Then we can form two different mono tracks. One of them will work as reference audio. For instance, see collection 452. If there is no way of doing that then we use MIDI. NB! This track is not audible to users.

- Demo track. The audio track that comes with the book. It usually gives the student an idea how everything should sound. MIDI is our choice only if we have no real audio tracks. Guitar chords played with MIDI sound awful and should only be used in the audio layer where nobody can hear them (the reference track). This is the track that is played the most.

Adding Sections

- Normal section. Place the cursor to where your section will begin and press 'Sections' from the left menu panel. Drag the size of the selection as you wish. Add a title to the selection and press 'Save'. That selection will now be part of the exercise and teachers will be able to assign only that part of the piece. We have used it for cutting an exercise into smaller sections (intro, chorus, verse, etc.), or for scales (each tonality is a separate section). There is a keyboard binding for setting the selection: ctrl+1 sets the left handle (beginning of the section) and ctrl+2 ends the section.
-Impro section. Select a section that cannot be assessed and press 'Set as improvisation'. That part of the exercise will be excluded from the assessment. It can be a guitar solo, spoken word, etc.
An exercise can have multiple sections.

Editing and repairing existing exercises

If you discover a mistake from an exercise, then the chances are that you don't have to recreate it but can repair it instead. Open an exercise that you want to repair and press 'Expert edit'. It opens the professional production tool and lets you go through all its phases.
Replacing a MuseScore file. The most common case is that you need to change the visuals. Make sure that the number of parts and bars remains the same. Otherwise, you will get an error. Upload the new file, bypass the mapping, and overwrite the old exercise by pressing 'Replace'.
Replacing the audio files. You can replace or add files. If the exercise previously had a different audio file, then you may need to map it again. The same applies if the piece previously did not have real audio files attached at all. However, if you add a backing track that is of equal timing and length with any existing audio files, you don't need to map it again.
Repairing the sync. If you discover an exercise that is not in sync, then move to Step 2 and map it again.

Documentation and archiving

Track your production activities so that you and other people could understand what (when, why, who) have you done even after you have forgotten everything.

Naming and storing files

Organize the files so that you can always get them in case you need to redo an exercise. A sample folder structure: main catalogue is 'Book Title With All Numbers' in which you have 'mscz' for MuseScore files, 'sib' for Sibelius files, 'mus' for Finale files, 'xml' for MusicXML files, 'art' for cover art and pdf files.

The 2017 version of the MMS allows some user groups to download the score and audio files from the existing exercises. It is meant for making the repairing work easier. Still, keeping a well-organized archive of all the relevant files is strongly recommended.