Difference between revisions of "Production Guide"

From MMS Wiki
Jump to: navigation, search
(Production tool how to use)
(Files and formats)
Line 38: Line 38:
3) '''Exercise description.''' OPTIONAL. It can be used for copyright, arranger etc. It can be set separately for each exercise or the whole collection<br>
3) '''Exercise description.''' OPTIONAL. It can be used for copyright, arranger etc. It can be set separately for each exercise or the whole collection<br>
4) '''Instrument.''' Taken from the score file. When set to 'multiple' then the recording option disappears.<br>
4) '''Instrument.''' Taken from the score file. When set to 'multiple' then the recording option disappears.<br>
5) '''Default [[score goal]]'''. 80% by default. Can be changed later and set separately for each [[assignment]]<br>
5) '''Default score goal'''. 80% by default. Can be changed later and set separately for each [[assignment]]<br>
6) An exercise can also have an '''attachment''' (a PDF or other image).<br>
6) An exercise can also have an '''attachment''' (a PDF or other image).<br>
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.
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.

Revision as of 14:37, 27 June 2019

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. This 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. Fresh 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 Impro section

Editing and repairing existing exercises

Replacing the MuseScore file Replacing the audio files Repairing the sync

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.

Old production guide (may still have some useful information)

What is MMS/PF and how it works Functionality Student view Teacher view Who is the user, what is the context

Tools Chrome MuseScore Sibelius Finale (Notepad) Audacity Google account For MMS/PF For accessing the metadata on Drive

Collections Adding collections (URLs) Naming and publishing collections Cover art (where to link, which formats and sizes to use) Adding an existing exercise to a collection (non-preferred use case)

Converting files From .mus to MusicXML From .sib to MusicXML From XML to .mscz

Editing on MuseScore

The 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) Excerpts/parts Exporting selections from one big file

Produce_exercise how to use Step 1: Upload .mscz file

Step 2: Collection and audio files Choose collection Upload audio files

Step 3: Which parts to keep which to delete? Naming the instruments Checking the boxes Backing track Choosing the reference track(etalon) Choosing the Demo track Advanced view Add new excerpt

Step 4: Aligning In tempo mode (when to use) Matching mode (when to use) ‘Save and Load’, how to use The grid What it is, why two? Moving and navigating (Home, End, Spacebar, PgUp, PgDn, Level of accuracy (depends on the context - if etalon is real audio then it just has to look good)

Step 5: Aligning the MIDI and real audio

Step 6: Play all Play individual files Review the sync Move with shift+click

Edit exercise page Review the sync and look Naming the exercise Default score goal Public vs not public Exercise description Attachments Sections Adding Youtube video Exercise page for admin Play all Play backing Play etalon Play demo audio

Documenting your things on Source Package Metadata spreadsheet General sfuff Create and use shortcuts Track time, avoid wasting it Use Google, read forums. If nothing helps, ask Kristo

Sibelius tips

Installing plugins in Sibelius:


We need 3 plugins: Convert Folder of Scores to Current Sibelius Version Batch transpose Convert folder to Music XML (preinstalled on Sibelius 7.5)

First two can be downloaded from here:


In Sibelius:

If transposing instrument (Trumpet Bb, Clarinet Bb, Alto sax Eb) but written as piano (make sure by listening and using a chromatic tuner): Use plugin Convert Folder of Scores to Current Sibelius Version to batch convert everything to current version. use plugin Batch Transpose to transpose everything (maj. 2 down in case of Bb instruments, Alto sax is in Eb, e.g. maj. 6 lower). Choose ‘Transpose by Interval’, ‘Save and close’ (see also the complete list of transposing instruments http://www.secretcomposer.com/Secret_Composer_Blog_Demo/Concert_Pitch_-_Instrument_Transposition_chart.htm ) continue with Batch Transpose and do an instrument change Batch convert to xml with the Dolet plugin

NB! You may need to use a separate computer for batch conversions. Sibelius windows will automatically open and close during conversions and it is easy to interrupt the process or crash the Sibelius. While the conversion is in progress, continue with already converted files in MuseScore. In MuseScore:

Drag all xml files to MScore window Open corresponding pdf Make all notes that have an audio sample (see from pdf) look the same as pdf. (Close the other files without saving) Fingerings> Select all similar elements, open inspector F8, offset so that visible, then adjust manually. Texts like ‘Count 1 2 3’ etc. delete! They will be misplaced in final exercise. Leave bar numbers as they are Adjust phrasing lines as needed Linearize (custom option from File menu) After linearizing, add line breaks as needed (usually 4-5 bars in a row). Breaks do not have to be in same places as in pdf, the point is to have enough space for our feedback colors. If it says “swing” then click on first note, then double click on Swing in text palette. Check playback sound. If not correct then F10 and change. If done, ctrl+S to a new catalogue (name it mscz)

Known MScore problems

Will not use correct playback instrument. E.g. if the xml says it’s a trumpet then transposition is correct (Bb) but playback instrument is Yamaha Grand Piano (default midi instrument). It has to be changed manually before saving the file. (this happens if the soundfont does not have same instrument as the source file asks for) Linearize has to be done in MScore because of line breaks - if linearize is done in server it will accommodate too many bars to one line. Linearize fails if D.C al Fine is at the repeat sign. Then only D.C a. F is done, not repeat. Linearize fails if D.C. al Coda. Goes straight to coda, ignores da capo. Swing playback can be started but not ended.

- Fine ei ole seotud konkreetse noodiga, vaid kogu taktiga (clarinet 15-p04_v6 ehk siis audio 82 Mango Walk.) MScore tips:

Beams: Ctrl+A and “auto”

Notation mistakes and problems that we discover

Chord symbols done as general text Instruments are almost never set correctly, e.g. Cello book: instrument was set as alto sax (partly as piano) Improvised bars - nothing is notated