MakeMusic
SmartMusic Finale Garritan MusicXML

MusicXML Documentation

Moderator: Michael Good

MusicXML Documentation

Postby Mark Johnson » Mon Dec 03, 2012 2:28 pm

Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them.

Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
Mark Johnson
 
Posts: 5
Joined: March, 2014
Reputation: 0

RE: MusicXML Documentation

Postby Michael Cuthbert » Mon Dec 03, 2012 3:50 pm

Dear Mark,

This is a wonderful addition to the musicxml world -- congrats on making it and all the work.

Best, Myke

P.S. I've noticed that Finale (at least 2011) interprets <fermata type="upright"> the opposite of what you'd expect if no <stem> direction has been defined on the note. It doesn't matter which direction the stem goes, if a <stem> is present then <fermata type="upright"> matches the spec. If it is not present then the fermata goes in the opposite direction as you'd expect. Here's a most basic example, that produces an unright fermata even though type is inverted, and an inverted fermata if type is
"upright" or missing, but putting <stem>down [or up]</stem> fixes the problem, even though I would think if <stem> were optional anywhere, it'd be on a whole note:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE score-partwise PUBLIC "-//Recordare//DTD MusicXML 2.0 Partwise//EN" "http://www.musicxml.org/dtds/partwise.dtd">
<score-partwise version="2.0">
<part-list>
<score-part id="P">
<part-name></part-name>
</score-part>
</part-list>
<part id="P">
<measure number="1">
<attributes>
<divisions>1</divisions>
<time>
<beats>4</beats>
<beat-type>4</beat-type>
</time>
<clef>
<sign>G</sign>
<line>2</line>
</clef>
</attributes>
<note>
<pitch>
<step>C</step>
<octave>4</octave>
</pitch>
<duration>4</duration>
<type>whole</type>
<notations>
<fermata type="inverted"/>
</notations>
</note>
</measure>
</part>
</score-partwise>


Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them.

Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
Michael Cuthbert
 
Posts: 70
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby Joe Berkovitz » Tue Dec 04, 2012 8:17 am

Hi Mark,

Thanks for your work on this. The site is a very helpful move towards a comprehensive online reference with visual examples, which has been badly needed. The site is already much more useful than the raw XSD.

I've already written at length on the list of the need for a true specification, and I've talked about what makes a specification different from a reference, so I won't repeat those points here in full. The main thing I have to say is that a spec, unlike a reference, describes the interactions between the various elements and attributes. The patterns and principles of these interactions are what we think of the "architecture" of MusicXML, and a spec will expose these patterns clearly and in detail, with visual illustrations as needed. The current tutorial does address MusicXML at this level, but is much too abbreviated to function as a spec.

Here are a few initial observations from looking at the site so far:

- the index listing all the references to a term in the XSD is extremely helpful

- the separation of the schema outlines into elements and attributes at a high level doesn't feel very useful, since elements and attributes typically are used in close combination. Consider having the level below
"Score Schema" be the topic list of "barline", "common", etc. and then freely mix attributes and elements below the topic level. Also, the topic classification should be more fine grained if possible -- granted that is hard to achieve without overlapping categories.

- There appears to be some kind of error in the generation of the contents and index. I could not find the important attribute "placement" described in any of the outlines, nor is it present in the index.

Regards,

... . . . Joe

Joe Berkovitz President

Noteflight LLC Boston, Mass. phone: +1 978 314 6271 www.noteflight.com

wrote:

Mark Johnson wrote:Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them. Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
Joe Berkovitz
 
Posts: 79
Joined: March, 2014
Reputation: 0

RE: MusicXML Documentation

Postby Mark Johnson » Tue Dec 04, 2012 10:15 am

Hi Joe,

Thanks for your comments. Right, I should have also mentioned that the index is not finished (it's currently missing all the attributes outside of attributes and barline). This will be complete in the next version.

Mark


Hi Mark,

Thanks for your work on this. The site is a very helpful move towards a comprehensive online reference with visual examples, which has been badly needed. The site is already much more useful than the raw XSD.

I've already written at length on the list of the need for a true specification, and I've talked about what makes a specification different from a reference, so I won't repeat those points here in full. The main thing I have to say is that a spec, unlike a reference, describes the interactions between the various elements and attributes. The patterns and principles of these interactions are what we think of the "architecture" of MusicXML, and a spec will expose these patterns clearly and in detail, with visual illustrations as needed. The current tutorial does address MusicXML at this level, but is much too abbreviated to function as a spec.

Here are a few initial observations from looking at the site so far:

- the index listing all the references to a term in the XSD is extremely helpful

- the separation of the schema outlines into elements and attributes at a high level doesn't feel very useful, since elements and attributes typically are used in close combination. Consider having the level below
"Score Schema" be the topic list of "barline", "common", etc. and then freely mix attributes and elements below the topic level. Also, the topic classification should be more fine grained if possible -- granted that is hard to achieve without overlapping categories.

- There appears to be some kind of error in the generation of the contents and index. I could not find the important attribute "placement" described in any of the outlines, nor is it present in the index.

Regards,

... . . . Joe

Joe Berkovitz President

Noteflight LLC Boston, Mass. phone: +1 978 314 6271 www.noteflight.com

wrote:

Mark Johnson wrote:Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them. Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
Mark Johnson
 
Posts: 5
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby George Litterst » Tue Dec 11, 2012 11:46 pm

Hi, Mark,

Your documentation is very help.

I notice that you have an example of the Schleifer. Can you tell me what font has this item? I am presuming that you created your example with a font character.

Thanks, George F. Litterst


Mark Johnson wrote:Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them. Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
George Litterst
 
Posts: 26
Joined: March, 2014
Reputation: 0

RE: MusicXML Documentation

Postby Mark Johnson » Wed Dec 12, 2012 9:50 am

Hi George,

I'm glad you find it helpful! You can find the Schleifer character in slot 122 of the Toccata font or slot 114 of the NovemberExtra font.

Mark


Hi, Mark,

Your documentation is very help.

I notice that you have an example of the Schleifer. Can you tell me what font has this item? I am presuming that you created your example with a font character.

Thanks, George F. Litterst


Mark Johnson wrote:Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them. Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
Mark Johnson
 
Posts: 5
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby George Litterst » Wed Dec 12, 2012 11:57 am

This is very helpful, Mark. Thanks!

George


Mark Johnson wrote:Hi George,

I'm glad you find it helpful! You can find the Schleifer character in slot 122 of the Toccata font or slot 114 of the NovemberExtra font.

Mark


Hi, Mark,

Your documentation is very help.

I notice that you have an example of the Schleifer. Can you tell me what font has this item? I am presuming that you created your example with a font character.

Thanks, George F. Litterst

Mark Johnson wrote:Greetings MusicXML pioneers,

I'm Mark Johnson, a technical writer here at MakeMusic, and I have been assigned the task of working with Michael to create a MusicXML reference, with musical examples, based on the MusicXML 3.0 XSD Schema. The objective is currently to create documentation that helps explain the capabilities of MusicXML as an interchange tool that allows users to accurately and efficiently transfer digital sheet music, with musical semantics and playback details, between applications. (Our scope does not include the creation of a W3C compliant specification, but it's possible this project could help facilitate such a specification in the future.)

<http://www.finalemusic.com/UserManuals/MusicXML/MusicXML.htm>

So far we have:

* Translated the XSD schema and annotations to a searchable, indexed webhelp project.

* Introduced comprehensive, descriptive tables of the schema
(elements, attributes, simple types, and complex types) with hyperlinks.

* Created a development procedure that ensures the annotations in the XSD match those in the documentation output.

* Introduced Michael's MusicXML 3.0 Tutorial.

* Added many musical and/or code examples.

I invite your feedback as we continue to improve this resource. As someone who has been doing documentation for a long time, I know that the most helpful content comes from an open and interactive dialog between the users and the writer(s) of the documentation. In your suggestions I ask for your patience, as I am not a programmer myself, and also please remember that my job is, specifically, to help improve the documentation and not MusicXML itself - that's Michael's job. I should also mention I've been eavesdropping on this list, and am delighted to see a community of users so enthusiastic about MusicXML and the creation of a specification. I know you have high expectations, and I hope I can accommodate them. Also, while this project has been a regular part of my schedule for the past few months, it will be interrupted, at some point, by my other responsibilities related to documenting MakeMusic notation products. I'll do my best to be a responsible steward, and keep you informed of any important changes.

I look forward to working with you.

Mark Johnson Technical Communications Specialist MakeMusic, Inc.
George Litterst
 
Posts: 26
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby George Litterst » Wed Dec 12, 2012 1:04 pm

Mark,

Would you provide more explanation for Doit, Plop, Falloff, Scoop?

I am unfamiliar with these symbols and the examples that I have found on the Internet are typically curved lines. Your current documentation, however, suggests that there are alternative representations. But, those represents and the printed examples that you show are not always consistent.

For example, the documentation for Plop states, "The line-shape attribute distinguishes between straight and curved lines." I presume this to mean that the element can be a curved shape or a straight line. However, the graphic example in the documentation shows a wavy line.

Can you point me to any font characters that would be considered to be standard representations of these elements, possible the Toccata glyph index: 181, 183, 197, and 199? If these Toccata characters are correct, can you tell me which apply to which element?

Thanks, George


George Litterst wrote:This is very helpful, Mark. Thanks!

George

Mark Johnson wrote:Hi George,

I'm glad you find it helpful! You can find the Schleifer character in slot 122 of the Toccata font or slot 114 of the NovemberExtra font.

Mark


Hi, Mark,

Your documentation is very help.

I notice that you have an example of the Schleifer. Can you tell me what font has this item? I am presuming that you created your example with a font character.

Thanks, George F. Litterst

George Litterst
 
Posts: 26
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby David Webber » Wed Dec 12, 2012 4:31 pm

> Would you provide more explanation for Doit, Plop, Falloff, Scoop?

These are all just glisses into a note or off it, and there's really no standardisation. In jazz charts you see curves, straight lines, and wavy lines according to the taste of whoever wrote it down.

Dave

David Webber Mozart Music Software
http://www.mozart.co.uk For discussion and support see <http://www.mozart.co.uk/mozartists/mailinglist.htm
David Webber
 
Posts: 148
Joined: March, 2014
Reputation: 0

Re: MusicXML Documentation

Postby Michael Good » Fri Dec 14, 2012 8:02 pm

Hi George,

As Dave replied, these symbols aren't too standardized. The doit and scoop have a upward direction while plop and falloff have a downward direction, reflecting the direction of the glisses.

The wavy line is represented in the line-type attribute as an alternative to solid, dashed, or dotted; line-shape is for straight vs. curved. I do see that the MusicXML doit example in the current draft doesn't match the graphic; the code is fine in the other three examples (falloff, plop, and scoop). We'll get that fixed.

Example glyphs in the Broadway Copyist with solid, curved lines would be slot 152 for falloff and plop, and slot 153 for doit and scoop. I don't have Toccata handy right now to check those slots.

Best regards,

Michael Good MakeMusic, Inc.


George Litterst wrote:Mark,

Would you provide more explanation for Doit, Plop, Falloff, Scoop?

I am unfamiliar with these symbols and the examples that I have found on the Internet are typically curved lines. Your current documentation, however, suggests that there are alternative representations. But, those represents and the printed examples that you show are not always consistent.

For example, the documentation for Plop states, "The line-shape attribute distinguishes between straight and curved lines." I presume this to mean that the element can be a curved shape or a straight line. However, the graphic example in the documentation shows a wavy line.

Can you point me to any font characters that would be considered to be standard representations of these elements, possible the Toccata glyph index: 181, 183, 197, and 199? If these Toccata characters are correct, can you tell me which apply to which element?

Thanks, George
Michael Good
VP of MusicXML Technologies
MakeMusic, Inc.
User avatar
Michael Good
 
Posts: 2197
Joined: March, 2014
Reputation: 0

Next

Who is online

Users browsing this forum: No registered users and 2 guests

cron