The new MuseScore 4 handbook

• Feb 11, 2022 - 11:07

MuseScore 4 will have an entirely new user interface, a new audio engine, and numerous usability improvements for everything from adding measures to setting the app's language. All of this will require a significantly updated handbook, which means plenty of opportunities for contributors to help build the documentation for the new version. Given the number of changes in MuseScore 4, it seems the right time to modernise the format of the current handbook while finding ways to improve the experience of looking for information.

The aim for MuseScore 4 has been to create the most user-friendly experience while producing high quality scores. Ideally, the more this ambition is achieved, the less reliant we'll all need to be on consulting an instruction manual. There will nevertheless remain situations where a guide to various features will be both useful and necessary, particularly when trying to achieve more sophisticated tasks. This is where a user manual can really come into its own, but it needs to be as thoughtfully designed as the product it describes.

Together with Marc Sabatella (Founder and Director, Mastering MuseScore), Peter Jonas (MuseScore Community Ambassador) and myself (Senior Designer, MuseScore), we’re planning to make the following improvements to guide people in making the most effective contributions while maintaining a cohesive and easily digestible handbook for everyone.

We'd be keen to hear your thoughts about these changes, and will be inviting community members to begin contributing articles following the alpha release of MuseScore.

More visuals

We'd like to adopt more of a "show, don't tell" approach for the new handbook (although written explanations will obviously remain essential – see more below). The idea here is that many instructional texts can be more quickly understood if a person can see someone else go through each step of a process. GIFs and videos will be vital to this end, and we'd like to make the best use of these resources as possible (especially GIFs, they're great).

Simplified language

Our aim is to use plain, simple language wherever possible, keeping both descriptive material and goal-oriented instructions succinct. A few ways we can simplify the use of language while decreasing some of the visual noise in the present handbook include:

  • Using only numbered lists for goal-oriented instructions (no dot points)
  • Beginning each numbered instruction with a verb
  • Writing only one task/direction per numbered item

Formatting considerations

Formatting enhancements will be constrained to a certain extent by the technical limitations of our content management system. At any rate, we intend to keep the existing "styled" keyboard shortcut visualizations (although we'll be seeking to improve their visual appearance), while also seeking typographical solutions that render hierarchical headings more visually distinct.

A new chapter structure

Moving away from the current "Advanced" chapter and relocating its contents to relevant and more discoverable chapters throughout the handbook

The current handbook makes certain assumptions about what constitutes "advanced" features, which may not be relevant to many people. For example, accessibility settings, far from being "advanced", will actually be fundamental for some people. Other features like fretboard diagrams might be used far more frequently by some people than, say, working with transposing instruments in concert pitch. To this end, it seems to make sense to promote all of the topics currently contained in the "Advanced" chapter to more sensible places elsewhere in the handbook.

Expanding the current "Notation" chapter, using a logic that makes musical sense

We'd like to kill three birds here with one stone (figuratively speaking, of course): 1) Accommodate some of the newly displaced "advanced" topics, 2) avoid an overly conflated "notation" chapter; and 3) make it easier to locate topics on musical-engraving matters. Our new-look "notation super-chapter" would contain separate sections for "rhythm and meter", "pitch", "measures, staves and systems", "expressive markings", and "repeats" (see more below).

New chapters dedicated to specialized notation

Separate chapters will be dedicated to notational elements specific to percussion, early music, and guitar. This also creates a structural pattern that can be used for other specialized notation topics in future.

A "go-to-first" chapter to get you started

This would take the form of one short chapter in the spirit of "if you only have time to read one thing, read this!". It will contain everything you need to know to create your first simple project, from adding instruments to exporting the final PDF.

Proposed new handbook structure

Note: We'll be setting up the below chapter and page structure on musescore.org, however we will be leaving the content of most of these pages empty so that the actual content can be authored by the community.

Editing the Handbook

  • Guidelines for writing articles
  • Use of non-written media
    • Creating animated GIFs
    • Creating video demonstrations
  • Formatting
    • Example code
    • Rendering
  • Syntax
    • Markdown
    • Permitted HTML

Introduction to MuseScore 4

  • Download and installation
  • New features in MuseScore 4
  • Create your first project
    • Creating a new score
    • Entering score information
    • Entering notes
    • Adding items from the palettes
    • Making adjustments in Properties
    • Inserting and deleting bars
    • Exporting your score

Basics

  • Adding and removing instruments
    • Deleting instruments from your score
  • Accessibility
  • Keyboard shortcuts
  • Object selection (formerly “selection modes”)
  • Copy and paste
    • Copy lyrics to clipboard
  • Note input (incorporating “Note input modes”)
  • Voices
  • Concert pitch
  • Palettes
    • Custom palettes
    • Master palette
  • Properties (formerly “Inspector”)
  • Instruments panel
  • Measures (formerly “Measure operations”)
  • Parts
  • Preferences
  • Score properties
  • Viewing and navigation
  • Workspaces
  • Timeline

File management

  • Open/Save/Export/Print
  • File formats
  • MIDI import
  • MusicXML
  • Recovered files
  • Score comparison
  • Share scores online

Notation 1: Rhythm and meter

  • Time signatures
  • Beams
  • Tuplets
  • Ties
  • Slash notation

Notation 2: Pitch

  • Clefs
  • Key signatures
  • Accidentals
  • Noteheads
  • Notehead schemes
  • Octave lines

Notation 3: Measures, staves and systems

  • Brackets
  • Barlines
  • Measure rests
  • Cross staff notation
  • Staff/part properties
  • Staff type change

Notation 4: Expressive markings

  • Articulations
  • Dynamics
  • Hairpins
  • Slurs
  • Breaths and pauses
  • Ornaments
  • Arpeggios and glissandi
  • Grace notes
  • Tremolo

Notation 5: Repeats

  • Repeats and jumps
  • Voltas

Idiomatic notation: Percussion

  • Drum notation

Idiomatic notation: Early music

  • Early music features
  • Figured bass

Idiomatic notation: Guitar

  • Fretboard diagrams
  • Tablature

Tools

  • Transposition
  • Implode and explode
  • Realize chord symbols
  • Respell pitches
  • Regroup rhythms
  • Remove empty trailing measures
  • Plugins

Text

  • Entering and editing text
  • Staff and system text
  • Tempo
  • Lyrics
  • Fingering
  • Chord symbols
  • Rehearsal marks
    • Resequence rehearsal marks

Formatting

  • Layout and formatting
  • Page settings
  • Automatic placement
  • Aligning elements
  • Frames
  • Breaks and spacers
  • Images
  • Image capture

Sound and playback

  • Play mode
    • Playback speed
  • Mixer
  • Soundfonts and SFZ files
  • Piano roll editor
  • Playback: Chord symbols / Nashville numbers
  • Capo playback
  • Mid-staff instrument changes
  • Swing
  • Unroll repeats

Support

  • Helping improve translation
  • How to ask for support or file bug reports
  • Revert to factory settings

Appendix

  • Command line options
  • Known incompatibilities
  • Upgrade from MuseScore 3.x
  • Upgrade from MuseScore 1.x. or 2.x
  • Handbook for MuseScore 3.x
  • Handbook for MuseScore 2.x
  • Handbook for MuseScore 1.x
  • Glossary

Comments

• Feb 11, 2022 - 13:42

Can we pretty please ensure that the url for the handbook contains the version number for all pages? So that everything for 4.x is a subpath of musescore.org/[lang]/handbook/4/
And also ensure that those pages that currently aren't are archived/moved into /3/ ?

Reply

• Feb 12, 2022 - 22:34

Mostly, yes. But I believe some pages are currently on a non-versioned link instead of on /3/ and ISTR (but am too lazy to investigate) that some /2/ pages are still on non-versioned links as well.

I'd also vote for adding a clear indication at the top of all older handbooks that they're not for the current version of the software.

Reply

• Feb 11, 2022 - 20:47

Re: "Using only numbered lists for goal-oriented instructions (no dot points)" -- generally speaking, this is industry standard. The rule is usually that unordered lists (bullet points) are used when the order of a set of items is not relevant. So, for example, if you have a list of three prerequisites that must be in place before doing something, those would typically be in an unordered list, often above the numbered steps of the immediate task. I don't know if MuseScore has many tasks that involve prerequisites...probably not.

And when a particular numbered item involves more than one operation, an alphabetical list (ex. Step 6 "a" "b" "c" etc.) helps the reader keep in mind the context for the specific action they are reading about. I know such nesting can be abused, where you get 3 or 4 levels within a parent step, and that's not a great experience. But I would not literally stick to a rule where every action always has numbered (not lettered) item, and there's never any hierarchy (sub task items) or bullet points anywhere in the doc.

EDIT: Not sure how many MuseScore tasks require more than, say, 5 steps. That would certainly impact the guidance on how to do lists. I'm used to documentation of tasks that involve 10-15 actions, often with dependencies and prereqs. So that colors my thinking on this.

Reply

• Feb 11, 2022 - 23:00

I think you're right that there are probably situations where an unordered list is certainly called for. Perhaps I was overly blunt in suggesting we should never use them :-)

I do, however, think there are ways we could improve this sort of example, where the bullet point to me seems superfluous and adds unnecessary visual noise to the entry.

An alternative in this example might be to put the desired goal in the sub-header, then simply specify the required action in a single line of body text beneath. So:

Add notes to a chord

Press Shift + A – G

(Or something similar, and obviously with keycap visualisation – this was just a rather quick example)

Attachment Size
Screenshot 2022-02-12 at 9.52.30 am.png 92.54 KB

Reply

• Feb 11, 2022 - 20:51

Speaking of accessibility, .gifs and videos need alt text, which I imagine would be covered in "Editing the Handbook", and it would be useful if the interface could validate the existence of alt text before saving these assets, though maybe that's too big a hurdle to leap.

Reply

• Feb 11, 2022 - 22:37

Sounds good to me and so far didn't find any ambiguous. Especially I appreciate, that accessibility wont be be an advanced topic anymore.

Reply

• Feb 11, 2022 - 22:55

A few suggestions.

  1. In the introduction section explain MuseScore's terminology. There are a number of terms that cause confusion for new users - e.g. system, voice, linked staves, parts, spacer, frame, break, chord, note, system/stave text. It would be useful to try to get new users familiar with these terms before they encounter them "in the field". This could probably use links to the Glossary section.

  2. Provide an alphabetic index to make finding specific items easier. (I wonder how practical this would be if the handbook is to be provided in many languages).

  3. If the handbook is to be provided in translations, please can we have a version that uses UK terminology - quaver, crotchet, minim, bar (not measure) etc.

Reply

• Feb 11, 2022 - 23:04

Really good suggestions.
Marc and I had actually discussed something about an index a while ago. We should revisit this idea I think (might be another big project for someone).
And if it is within the realm of possibility, a translation that uses UK terminology would be very valuable (Speaking also from my point of view as an Aussie – incidentally, where there are a lot of MuseScore users).

Reply

• Feb 12, 2022 - 01:44

As an aside mention: It'd be nice if MP4 or something similar could also be used in the handbook. GIF files are sufficient, but at the moment the forum imposes an an attachment limit of I think 4MB, and they are much larger in size compared to an x264 video equivalent in duration. Forum currently doesn't support the format, but it would be a space saver, and also would save the would-be demonstrator from performing extra conversion processes.

Reply

• Feb 13, 2022 - 23:39

This looks good.

Will there be a translation environment that will allow to view the handbook versions in several languages for a reference? The english version will be the 'official refence' of content I suppose. ¨

I might have organized "Programming - >Plugins, API, Changes from MS3 to MS4, Changes from MS1 and MS2 to MS4, Examples, What ever" instead of "Tools -> Plugins".
So MuseScore 4 will be scriptable. Is the script language the same as in MS3? Will the MS4.0 allready have a working script engine? Will there some day be another, deeper programming language?

You probably know what developments are planned for the next couple or more of years. Will they nicely fit in the proposed handbook layout?

Reply

• Feb 17, 2022 - 11:55

I'd expect the translation envirionment to be the same as we had before, for the 1, 2 and 3 handbook. And yes, the English handbook will be the reference, like it always was.

The scripting language for MuseScore 4 hasn't changed vs. MuseScore 3 (or shouldn't have changed) except for some additions and a newer Qt version so ECMA 6 is now supported

Reply

• Feb 19, 2022 - 23:42

Alright, I might help doing some translations, hand book and the programm itself, when the style of translations and the translated terminology in my language start looking coherent. Then about scripting, I really thought that the complete software rewrite would have forced major changes in the API.

My thanks to everybody involved in the MuseScore 4 project!

Reply

• Feb 18, 2022 - 19:23

Although I haven't much time to devote to this so far - and until recently couldn't get MuseScore 4 builds to work reliably for me - I do plan to take a more active role in this going forward. In particular, I plan to do some amount of writing, especially the "harder" sections that I think needed rewriting from MuseScore 3 anyhow, by the time the alpha happens and we open things up for general participation. And I'll continue to contribute on an ongoing basis, but also, I'll step in as an "editor" where necessary to try to ensure a certain level of consistency and quality.

Reply

• Jun 6, 2022 - 17:25

May I propose a chapter: "Idiomatic notation: arabic music". As I understood Musescore supports quarter tones (both playback and its accidentals in notation) as well as meterless notation. This, and eventually some special key signatures is all that is needed to notate arabic music. Maybe a short chapter explaining how to write in metered/meterless format, accidentals, and plugins to install.

Reply

• Jun 6, 2022 - 17:47

Great idea! Probably non-Western in general. MuseScore does support custom keys. Each of these things will be converted individually, but a page showing how to use them specifically for different types of non-Western music could be useful indeed. If we create such a page, we would just need someone sufficiently versed in these styles to help write it - would you be willing?

Reply

• Jun 6, 2022 - 18:24

I am definitely not the best candidate, both because I am not an expert user of Musescore, and because I have no experience in writing user documentation, but I am willing to spend some evenings on such work, especially if I can get help from the core team for my questions and someone can proofread and correct my work.

Reply

• Jun 6, 2022 - 18:10

I would like to propose a couple of extra items to the chapter of "Idiomatic notation: Guitar"
- Notation of harmonics (both in notation and in tablature). Easy as it sounds there is no 100% accepted standard for harmonics and for example Finale and Guitar pro have built in default notation for harmonics that is completely different.
- Spanners: show different type of Musescore spanners applied to guitar notation: barre sections, marking sections as played only with thumb. section of palm muted sounds,etc.

Reply

• Jun 7, 2022 - 14:21

Thanks! FWIW, I deliberately didn't include fingering because there is a whole separate page for that, and in general I was trying to avoid duplication. But, no reason there can't be a section here to explain the different types of fingering, perhaps give some very basic info on entering them, then link to the main fingering page. I've edited the page to suggest that.

Reply

• Jun 7, 2022 - 15:46

We write in Markdown (much simpler than HTML) then an internal tool converts it to HTML for display. So all editing is done in Markdown.

But right now, we’re still setting things up and haven’t opened it for general editing yet. When we do there will be an announcement. And at that time it will be possible to edit by clicking the “…” menu at top right of each page.

Reply

• Dec 24, 2022 - 11:34

Io mi sento solo di RINGRAZIARE tutto lo staff e gli ideatori di questo STUPENDO SOFTWARE, da quando lo conosco mi ha letterlamente facilitato la vita, una cosa interessante da implementare sarebbe la possibilità di inserimento via MIDI delle note in tempo reale, cioè registrando le parti come in un sequencer MIDI. (premetto che non ho ancora utilizzato la versione 4, mentre lo stavo facendo il l'applicazione purtroppo si è chiusa e purtroppo ho perso il mio lavoro, anche se avevo iniziato da poco, per sicurezza ho terminato il lavoro con la versione 3.6, molto stabile).

Reply

• Dec 27, 2022 - 02:36

I'm not sure how extensive the Glossary will be but I suggest that you include definitions for beginners as well as for those with more experience. I have been involved in music most of my 72 years but there are many terms which I am unacquainted with. Many are somewhat basic terms. The more technical the term is, the more simple the explanation should be so those of us that don't know the meaning can understand it. I have been using MuseScore since version 2 was released and I won't change! I recommend it to everyone that I talk to about music composition softeware.

Reply

Do you still have an unanswered question? Please log in first to post your question.