Borframework.txt - BrailleOrch Software Development Framework By Hu Haipeng Date: Jan 31, 2016 First draft: Feb 26, 2016 Last updated: Jan 16, 2017 Project holder: Daniel Barich Project designer: Hu Haipeng Project development website: https://github.com/barichd/brailleorch Copyright (C) 2015 By Hu Haipeng and Daniel Barich ======================================== BrailleOrch is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. BrailleOrch is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with BrailleOrch. If not, see . ======================================== Contents Preliminary Materials 1. Purpose 2. Requirements 3. About BrailleOrch and BMML Format 4. About This Framework 5. Working Progress Chapter 1: Menu Overview 1.1 File Menu 1.2 Edit Menu 1.3 View Menu 1.4 Navigation Menu 1.5 Transcription Menu 1.6 Braille Music Menu 1.7 Playback Menu 1.8 Options Menu 1.9 Window Menu 1.10 Help Menu Chapter 2: Deeper view of transcription function 2.1 Transcription Dialog 2.2 Transpose dialog 2.3 Score Management Dialog 2.4 Part Management Dialog 2.5 Text Management Dialog 2.6 Lyrics Management Dialog 2.7 Chords dialog 2.8 Metronome Dialog Chapter 3: Braille Music Editing And Debugging Related Points 3.1 GUI specifications 3.2 Entering And Marking Items, transcription related 3.3 Debugging Mode Chapter 4: Options Dialog 4.1 General Page 4.2 Transcription Page 4.3 Single-line Page 4.4 Bar-over-bar Page 4.5 Line-over-line Page 4.6 Section-by-section Page Contact Information ======================================== Preliminary Materials 1. Purpose This is a detailed framework of BrailleOrch, braille music transcription software for advanced formatting and publishing purpose. The final software will convert Musicxml files, or via a separate plugin, Sibelius files, into our extended Braille Music Markup Language (BMML) format (originally created, developed and copyrighted by Veia Progetti s.r.l. [http://www.veia.it], Italy, as free software. See copyright information in the BMML package for details), which can be flexibly edited and modified, to fulfill most of the requirements of braille music publishment. Since this software is free, and under GPL and Veia free software licenses, anyone who are willing to help us can join in to develop and enhance it. We welcome people around the world to do anything making convenience to braille music production for blind musicians. ---------------------------------------- 2. Requirements An experienced Python and XML knowledge is required for developing this software. A basic Github knowledge is required for committing changes. Knowledge of music, musicxml, braille and/or braille music is recommended, which will largely enhance the efficiency and quality of development. Sibelius Manuscript Language is required if anyone who wants to make a BrailleOrch export plugin for Sibelius (see the fourth phase in section 5). Some items in Sibelius can't be correctly exported into musicxml via its internal export function and/or Dolet For Sibelius plugin. The software will run under any Microsoft Windows systems, from Windows 2000/XP to Windows 10, both 32 and 64 bits. A screen reader such as NVDA is required for announcing unicode braille objects. Music publishers and sighted braille transcribers are not asked for this option. ---------------------------------------- 3. About BrailleOrch and BMML Format BrailleOrch (.bor) format is a compressed file. It contains original musicxml (if transcribed from musicxml) and bmml sources, and additional debugging information such as error records. When the final editing and correction has been finished, the musicxml source and most debugging information can be removed to save file size. People can still edit and reformat braille output, though. See Make final document in File Menu. For BMML format, I think we should design two stages. The one is the current format, and we can just extend it to include more signs and functions. This kind of BMML file contains both musical and braille information. The second one is a BMML file which is just a mapped format from Musicxml, and is ready for braille transcription. Music publishers can first generate such an intermediate file for transcribers or end users, and the braille users can check and format music with their own preferences. This format can be developed later, since it needs very smart on-the-fly formatting. and previewing functions of the software. This format is inspired by Sunshine professional, a Chinese braille translation software made by China Braille Publishing House. The wording, hyphening and formatting are constantly changed while the user is editing the file, like MS Word, and this interface is very friendly and smart. ---------------------------------------- 4. About This Framework This comprehensive document will describe all menus and functions of BrailleOrch. People who wants to develop/enhance the software must read it carefully. It will, however, not discuss the development of current BMML and Musicxml to braille transcription issues. These will be discussed either in a separate article, or in a future mailinglist or forum. Only critical requirement of changes needed to be done are shown. ---------------------------------------- 5. Working Progress Since this is an extensive project for a highly sophisticated software, we have to divide the development session into several phases. The first phase is to build up a general GUI, containing basic menus and functions. Use original BMML source to define and enhance braille music transcription. Missing signs in BMML DTD must be added. Basic functions in Page setup, Score/Part/Text/Lyrics/Chords/Metronome management and Transcription options dialogs should be done. Bar-over-bar and line-over-line formats are firstly considered. The result braille music score can represent at least 95% information of print version. The score can be manually edited, but not reformatted and retagged automatically, since this requires deeper research of BMML and further development of the software. The user-edited strings are gray-colored, and simply marked as "other" in BMML, and can be tagged in future versions of the software. The second phase is to enhance transcription quality. Items in Musicxml 3.0 or later should be added, and the formatting function must be more flexible. Add section-by-section format. Enhance translation table to add support to Chinese Mandarin braille (Cantonese and Taiwanese Chinese braille have already been done in Liblouis). The third phase is to enhance the reformatting function. The software can recognize most user-entered strings as music signs, texts etc, and can correctly break lines when reformatted. The fourth phase is to develop a Sibelius plug-in, directly exporting .bor files from Sibelius. Musicxml exported from Sibelius has some information missing, because there are special user items. We can use Manuscript Language to make the braille version more close to the original score. Unspecified items can also be exported and tagged for manual editing. BMML exported from this plugin is not correctly formatted, so this tool has to be delayed to the time BrailleOrch is powerful and flexible enough. The last phase is to develop the braille music composing function. Since the software can already recognize common braille music signs entered, the main focus is on advanced signs, creating parts and groups, writing chord symbols, handling visual appearance, Midi functions etc. ======================================== Chapter 1: Menu Overview This chapter describes all menus and submenus. It gives us a brief view of the major functions of BrailleOrch. 1.1 File Menu New To create a new BMML document. This will not be considered currently, unless we decide to develop braille music composing side. Braille Music Editor 2 from Veia Progetti can do a intermediate level work of it, and blind musicians can now use ABC, Lilypond and Sibelius to produce print music scores. So our main goal is to develop a transcription software. Open Open a BMML file (.bmml), both original Veia version and our extended new version. Our new version contains more information and functions, so for portability purpose, it will be a compressed xml file with the extension .bor. Another kind of unprocessed .bor file can also be opened, see Import. Open recent A list of recent created/opened files. Number of files can be set or cleared in Options dialog. Save Save the current BMML file in either BMML or Bor format. The BMML format is not an old version of BMML, but an uncompressed Bor file. This can be used for researching the format to help developers get familiar with BMML. Save As Save the file using a different name or to a different location, in either BMML or Bor format. Versioning (submenu) Save Version open Version Versioning function is for further comparison of the score. The version files will be saved using .bor format, with a time/date stamp after the extension. E.G., foo.bor~01312016. Saving an earlier version will bring up a dialog, asking whether you want to save a new version or overwrite the current non-version file. Set copy protection This is a special function for protecting music pubisher's copyright. After they convert their scores into musicxml and import into BrailleOrch, they can immediately set this option. The file can still be edited, reformatted and embossed, but can't be exported into musicxml for back-translation. The file is also encrypted, so it also can't be saved as bmml format. Any debugging process upon the xml source and bmml score can, however, be done using the internal debugging interface. Be careful to use this function, since it's not reversable. We should provide two times of verification dialog for this. Another possibility is, we can toggle this item visible and invisible in the "Option" dialog, to prevent accidental operation by common users. Make final document Be careful to use it like Set copy protection. This will remove musicxml source and most debugging information from the file. So don't use it before the final correction of braille music is done, especially when there are errors. As I said before, the metadata will be protected using Set copy protection function, so the protected musicxml source can't be extracted. So don't worry about the source. After making the final document, people can still edit and reformat braille music score, but can't debug and make enhancement of the software. Close Close All Close the current working document(s). Import Import Musicxml files, from version 1.0 to the latest version, both compressed (.mxl) and uncompressed (.xml). The transcription process will begin, see Transcription dialog for details. Import ASCII/unicode braille file, making ASCII2Unicode or vice versa conversion according to chosen braille table. This will not automatically generate a bmml format, but just storing and converting original data. This way, the .bor file is just a compressed version of original source. When we decide to develop braille music composing side, this situation will be changed. Importing MIDI file will also be considered in the future. Export Export MIDI and Musicxml formats. This will be considered later. Export to unicode or ASCII braille. This is the current function. When exporting to ASCII, an option dialog will appear for choosing a braille table. Different country uses different braille mapping table. Page setup Settings for braille pages. In this dialog: Lines per page: line amount spin editbox, default 25 Cells per page: Cell amount spin editbox, default 32 Adding form feeds: checkbox for inserting form feeds. Default checked Print page numbers: braille printing page numbers. Default checked Print page number position: combo box, topleft, topright, bottomleft and bottomright. Default topleft Braille page numbers: braille braille page numbers. Default checked Braille page number position: combo box, topleft, topright, bottomleft and bottomright. Default topright When these two positions get conflicted, a warning message will appear, asking the user to adjust the position correctly. Show page turn: checkbox, visible when Print page numbers is checked. Page turn includes dots 5 2-5 with (or without) new page number. Page turn format: combo box. Choices are: within music, above music, within music without page number. Emboss Emboss braille music scores using installed braille embosser drivers. Exit Quit the software. ---------------------------------------- 1.2 Edit Menu Undo Undo the previous operations. Redo Redo undone operations. Undo history A 128-step history list, to choose an undo item to roll back or forward. Select all Select all items. Special selection (submenu) Set begin of selection block (F5) Set end of selection block (F6) Set from begin to current location (F7) Select from current location to end (F8) Select line (F9) (current print line of current part, from beginning to end measures) Select part (F9) (current part, for whole piece/movement) select staff (F10) (current braille staff) Select system (F12) (current braille system. System means a whole group of staves, showing all instruments and voices playing simultaneously.) Remove selection (F4) (remove the current selection. The selection will not be removed if this is pressed, or a new selection block is made.) Cut/Copy/Paste/Delete Cut/copy/paste/delete selection. Cut/Copy/Paste/Delete part/voice/measure/measure of the system The same cut/copy/paste/delete function for curent location or selection, but deal with different items. Search/replace Common search/replace functions. However, there's an checkbox to switch on "searching for texts", which switches of unicode braille input (fsd for d-ots 123, jkl for 456), and directly search within the xml sources for standard texts, including dynamics and any text-based values. The result will bring the cursor to correct braille location. ---------------------------------------- 1.3 View Menu The common view menu for sighted users. It includes simple view options such as zooming, visibility of toolbar, and braille reading modes etc. Braille reading mode will give us options to choose white-screen-black-dots or black-screen-white/blue/green-dots. ---------------------------------------- 1.4 Navigation Menu Besides common arrow navigations of individual braille cells or lines, there are some special functions. Next note (tab) Previous note (shift+tab) Next beat (alt+right) Previous beat (alt+left) Next measure (ctrl+right) Previous measure (ctrl+left) Next voice (win+right) Previous voice (win+left) Next part in the same measure (ctrl+down) Previous part in the same measure (ctrl+up) Next print line (alt+down) Previous print line (alt+up) Next braille system (win+down) Previous braille system (win+up) Next print system (ctrl+win+down) Previous print system (ctrl+win+up) Next braille page (pgdn) Previous braille page (pgup) Next print page (ctrl+pgdn) Previous print page (ctrl+pgup) Begin of current braille page (home) End of current braille page (end) Begin of current system (alt+home) End of current system (alt+end) Begin of file (ctrl+home) End of file (ctrl+end) Go to measure/part Enter measure and part numbers. If measure number is left empty, then stay in the current measure; ff part number is left empty, then bring to the first part of the measure. Go to selection (submenu) Go to begin of selection (ctrl+F5) Go to end of selection (Ctrl+F6) ---------------------------------------- 1.5 Transcription Menu This menu handles various transcription functions. Transcribe This is a manual action of transcription. If the user wants to start from fresh beginning to undo all previous modification, or after debugging problematic musicxml file, this will start a new transcription session. Transcription dialog will or will not appear according to setting in the dialog or Options dialog. Bar-over-bar (default) Line-over-line Section-by-section These 3 options will change the current format of score. The formatting will be done according to settings in Options dialog. We highly recommend people to set their preferred format as default in the Options dialog, to reduce any messy formatting problems. All detailed options for these formats can be found and will be discussed in the Options Dialog section. For single-staff instrument solo, the above will be unavailable, and settings for single-line format will be applied. See corresponding settings in Options dialog for details. Format Format or reformat the braille score after manual editing and correction. Formatting layout will follow rules set in Score/Part/Text/Lyrics/Chords/Metronome, Options and Page setup dialogs. Options changed after transcription process can also be applied. Debugging mode A special mode used for checking errors and enhancing the software. See Debugging Mode for details. Output interval direction description A dialog appears, letting you to view the description. There are 2 kinds of description: 1. When all intervals are up/down, it will let you choose from two methods of descriptions: a. Literary: All intervals are read upwards/downwards; b. Notation: a C with second interval sign, space, two dots 3-5's, space, two notes with in-accord, either C-D or C-B. 2. When different intervals are used, it will show as: All intervals are read upwards/downwards, except blah blah, which is/are read downwards/upwards. Output part list See this item in Part management dialog for details. Extract parts Extract parts for players/singers. A dialog appears, letting you check part(s) to extract. New .bor documents with only bmml sources for individual parts will be created. You can change the order of parts, or choose whether to extract parts as individual files or just one file shwing parts one by one. If "combin individual parts" is checked, the result file will generate a full score containing selected parts (this is useful for publishing choral scores containing vocal parts only). Combine parts to score A reversed operation of part extraction. A dialog appears, letting you add files and adjust their order. But the files must be the whole parts of the same piece, otherwise BrailleOrch will refuse to go ahead. BrailleOrch will first check the coincidence of time and measure among all parts, and shows a warning message telling which file(s) are unmatched. BrailleOrch will check coincidence according to the topmost file. ---------------------------------------- 1.6 Braille Music Menu This menu gives us several functions of editing and correcting braille music score. Some are very sophisticated functions. This menu will be modified and extended when we decide to develop braille music composing function. Input (submenu) Insert notes (n) Enter notes/rests/voices, generally all music-related signs. Insert texts (x) Enter texts using standard input method. Untranslated unicode texts such as Chinese will be accepted, and can be edited later. All text-related adjustment can be done in Text management dialog. Insert key signature (k) Insert time signature (t) These two use braille input. Insert chord names and figured bass (c) Braille input of chord and figure symbols. Insert title page information (i) Insert title info at top of system. See Score management dialog for details. There's a checkbox for inserting title info on a blank page. If checked, a blank page will be created. Insert footnotes (o) Add a line of dots 3-5's plus footnotes. Insert division signs (v) Centered 12 division characters. Choose from dots 3-5 and dots 5. Insert new print page (shift+p) Insert new braille page (shift+b) These are for modification and/or reformatting, or when no print pages are available in musicxml 1.0. Also useful when developing braille music composing. Print page will be inserted at the beginning of the measure, while braille page will be inserted at the beginning of the current braille line. Set current measure (m) Set number of current measure, overriding measure numbers in Musicxml. The consequent measure numbers will be changed accordingly, until Musicxml specifies a new sequence of measure number (e.g.,, starting a new movement from measure 1). Set current braille page (b) Set current braille page number. The extra choices for numbering are arabic, roman, lower-celled and (for title pages) none. Set current print page (p) Set current print page number, overriding Musicxml's settings. The extra choices are arabic, roman and none. Other tags and properties can be marked using context menu directly on braille objects. Transcribers can also edit the score without using the above insert and context functions, but the result input will be marked as "other" in BMML, and can't be automatically reformatted correctly. They should be manually formatted. Display images This menu is for extracting pictures contained in compressed Musicxml files (.mxl), which may be cover page images or special music symbols not being able to enter in notation programs. The listbox describes the details of every image file as this: filename, part number, staff number, and bar number. Press View to read the image on screen, and press OK to bring the cursor to the location for transcribers to enter appropriate braille symbols. Transpose This dialog will handle score/parts transposition. See corresponding chapter for details. Score management A tool for managing various items such as page/measure numbering, movement divisions etc for the whole score or selected block. See corresponding chapter for details. Part management A very powerful tool for managing part names and grouping properties in the score. See corresponding chapter for details. Text management A very powerful tool for managing various text items in the score. See corresponding chapter for details. Lyrics management A tool for managing lyrics in the score. See corresponding chapter for details. Chords management (to do it later) A tool for modifying chord symbols. Metronome management A tool to manage metronome marks in the score. See corresponding chapter for details. ---------------------------------------- 1.7 Playback Menu Play/stop (ctrl+l) Play current measure (shift+l) Play current part (ctrl+;) Play current voice (shift+;) Play metronome (default unchecked) Choose instruments List out all parts and their midi instruments. Assign button will bring up a dialog containing a 128-line list of GM instruments. By default, BrailleOrch will assign correct instruments according to settings in Musicxml. BrailleOrch should be able to use multiple instances of GM modules to handle more than 16 parts. Play sounds when navigating (default checked) Whether to play MIDI sounds during cursor navigation. Default: checked. Playback device Choose from available sound devices for Midi playback. ---------------------------------------- 1.8 Options Menu Options Comprehensive settings dialog. Discussed in separate chapter. Announce modes (submenu) silent Braille only Objects only Braille and objects (default) ---------------------------------------- 1.9 Window Menu Standard window menu, such as tile, cascade etc. ---------------------------------------- 1.10 Help Menu About User manual (F1) Software website Check for updates ======================================== Chapter 2: Deeper View Of Transcription Function This is the core of the software, so please be careful to read it. For knowledge of braille music, please consult New International Manual Of Braille Music Notation (SBS, 1996) and Music Braille Code 1997 (BANA) . The latter contains more information about different formats used in braille music, and also some extra signs. The software will treat score with only one part with one staff as single-line format. It will automatically treat score with only one part with two to four staves as piano (or organ, chosen by the user) format. It will treat score with one single-line part above one multi-stave part as solo with keyboard accompaniment part, and add dots 5 3-4-5 before the single-line part. 2.1 Transcription dialog Note: All dialogs in this software have "ok" and "cancel" buttons. When importing a Musicxml file, the software brings up a dialog, giving the users options for adjusting transcription appearance. It can be turned off by checking Don't show this dialog again at the bottom of the dialog, or via Options dialog. The last settings will be stored, and users can override these options in Options dialog. The Transcription dialog also contains lots of buttons to bring up corresponding options in that dialog. Transcribe without formatting This checkbox will generate a non-formatted braille score, disregarding layout settings. This kind of bmml file only has musicxml-mirrored objects, no braille indications are included. Users can edit the score and then use Format in Transcription menu. This must be reserved for future use when we develop the second stage of BMML. Braille score format Radio buttons: bar-over-bar, line-over-line and section-by-section. Default is bar-over-bar. When one format is chosen, the corresponding option button will be shown, bringing user to corresponding items in Options dialog. Page setup Brings up Page setup dialog in File menu. Starting braille page Starting print page Starting measure number These 3 edit boxes let the user fill in specific numbers overriding musicxml's values and default braille transcription settings. Score/Part/Text/Lyrics/Chords/metronome management Bring up corresponding dialogs which are also available in Braille Music menu. Transcription settings Bring up Transcription settings in Options dialog. Translation table Used for text translation. This can also be seen in Options and Score/Part/Text/Lyrics/Chords management dialogs. Add hand change signs for selected passage This is for piano or other 2-staff music. See the same item in 3.2 for details. Don't show this dialog (default unchecked) Disable this dialog, using options previously set. ---------------------------------------- 2.2 Transpose dialog Transpose (radio button) Display original transposition (default) Display in concert pitch Transpose the whole score (display a combo box for transposing the score in half steps, both plus and minus values are available. The max value is +/-24.) Transpose parts (display a list of all parts with checkboxes, and a combo box for transposition. The combo box will only take effect on checked parts.) When transposed, the BMML must have a record of original key. So if we come back to original key by selecting the first option, all parts can be rolled back to their original keys immediately. ---------------------------------------- 2.3 Score Management Dialog Description of the score This is a read-only text box, showing summary of the score. Available items are: general header, individual headers (headers with their starting print/braille pages), number of print/braille pages, number of measures, page format, score format (single-line, bar-over-bar, line-over-line, section-by-section). Running header: some countries have running headers at the top of page. A general header can be set here. Some books use different header on different piece. This can be done by specifying individual headers using context menu within the score, and will override the general header. Title/Subtitle/Composer/Lyricist/Copyright/Other These edit boxes will be automatically filled if they can be retrieved from Musicxml source. Otherwise the user can enter them here, and the braille will be automatically generated and formatted. User can also insert them form Insert title page information dialog under Input submenu of Braille Music menu. If entered as braille manually, they can also be tagged later using context menu. The result braille can be copied/cut/pasted freely on the page. Table of contents dialog This can be written in the braille window, but can also be done here. The difference is, the one set here can function like TOC items in MS Word, bringing the user to corresponding location. TOC title: Enter normal text, and the software can handle it correctly. The TOC format is title plus dashes or dots (dot 3 or 5) plus page number. There are 2 columns, one for title, one for braille pages. Indentation is automatic. Division patterns Radio button: dashes (dots 3-6), dot 3 and dot 5. Indentation: edit box. Default, by 2 cells Context menu for the above items should add "Translation table". Note: 1. Current untranslatabre texts such as Chinese characters can be manually translated via Text management dialog in context menu. 2. If items in this dialog are removed completely, and no user-entered info are on title and TOC pages, the blank pages will always be removed automatically. Division signs will be removed even they are not deleted here. ---------------------------------------- 2.4 Part Management Dialog Some Musicxml files have long part/abbreviation names, some have missing part/abbrev names, some have group names for group of staves, and some have instrument changes during the music,. These are not able to be transcribed correctly. Here's a powerful tool for solving this problem. Part names and abbreviations will be automatically transcribed into braille, except Chinese, which can be edited in the Braille parts list table. All line breaks in the Musicxml part field will be shown as \n, and discarded in braille version. Such kind of part names must be manually edited. Print part list List all original items in of Musicxml, plus part names caused by any instrument changes during the music. Items in this extensive table view can be navigated using arrow keys, selected using shift+arrow, edited by pressing F2, and deleted using Del key. Its format is managed as follows: group name, group abbreviation, part ID, part name, and part abbreviation. If there are part names of instrument changes, these names and abbreviations will be marked as "instrument change". Any item will be left empty when no one is found. Staves in a group will display group name and abbrev on all staves. When a multi-stave part is available, number or letter sequences will be added after the abbreviation names. Default is number. Context menu items Undo/Redo Common undo/redo function. Combine these staves Piano/harp/organ parts in some orchestral scores are not grouped correctly. Select this to make selected staves into group. Treat as piano Change current group into piano format, thus adding hand signs before each staff. You can delete part names not belonging to the first staff. Treat as organ The same as piano, but treat the 3rd staff as organ pedal. Treat as multi-stave parts Some divisi parts have only two staves, and will be ocassionally transcribed as piano parts. Use this to turn them into common multi-stave parts. The individual names of the staves can be further edited. Use group name select if the part names in a group are missing or just arabic or roman numbers. E.g., some scores mark "Horns in F" as group name, and "I II" "III IV" as part names, no abbreviations or abbreviations are the same as part names. But such modified abbreviation names must still be edited for braille use. Use letter sequences for multi-stave part Select if you want to use letters for current multi-stave part, e.g., vln1a, where numbers have already been used. Use number sequences for multi-stave part The opposite way of previous item. Braille part list This table is used for editing braille which can't be correctly transcribed. Braille input will be activated by pressing F2. These two tables are linked, so scrolling one of them will also make the other scroll. Interval direction Radio buttons up/down to control interval and voice reading direction of current selected part(s). Default is down for all parts in score without piano-property parts. Keyboard (including keyboard with solo) All up All down All up except keyboard All down except keyboard This 5 buttons will make interval direction changes globaly. Keyboard applies only to parts with piano property, including organ and harp parts. When All up or All down applies to keyboard, the special hand signs should be used, i.e., 4-6 3-4-5 3-4-5 for treble reads upwards, etc. Disregard instrument changes Will always use default part names and abbreviations. ---------------------------------------- 2.5 Text Management Dialog A comprehensive dialog like Part management dialog. It lists out all texts items in the score. For dialog opened in this way, only words, credit items, DoletSibelius unrecognized system texts and rehearsal marks are listed. When opened using context menu, items such as title page and TOC info can be displayed. Text list A same table as part list, but with different layout: measure, beat, part, voice, text, braille The list is sorted timewisely by default. Blank spaces at the beginning/end of text block will be automatically removed, and can be manually entered in braille if needed. One difference is, the Del key will remove the text from the score. So please use F2 to clear and re-edit it. Context menu Undo/Redo Common undo/redo function. Translation table Choose one for current text. When using word signs, all uppercase will be ignored. Mark as dynamic Some special dynamic markings such as "sffzp" are not treated as dynamic in notation programs. This will tag the current text as dynamic mark. Mark as metronome mark This will change the property into metronome mark. Sometimes, special metronome marks are not assigned correctly in Musicxml. BMML must be re-designed to accept user-defined texts as metronome marks. Put word signs before every word Mark as rehearsal mark Rehearsal mark will be parenthesized, either within or above system. Long text blocks Use parenthesis These are 3 different functions. The first adds dots 3-4-5 before every word in the text block; the second puts dots 3-4-5 around the whole block, and makes a space before (except fore after part name, hand sign, sign for begin of repetition and clef sign) and after (except for end of line) the block; and the last adds parenthesis to the block, with a space before (except for the same condition) and after (except for the same condition) it. Chinese texts This will add Chinese music parenthesis (dots 5-6 3-6 and dots 3-6 2-3) around the text. Once the Chinese translation is available, this option will be removed. Treat as texts as This dialog has the following: inside music, outside music (plain), outside music (with word sign), outside music (with parenthesis), and non-music texts. These choices will move current selected text items inside or outside the staff. By default, non-title/credit texts are inside the music. When texts are outside the music, it will be normal text without word signs, or single word with word sign, or multiple words surrounding by word signs, or words in parenthesis, placed on top of the staff it belongs to. Non-music texts are some long text blocks such as title or performace instructions (some musicmxl files have title information attached to score, or marked as Sibelius system texts), or top-system texts attached to the first staff. When the first staff is empty, this option will move the text out and remove the empty staff in cutoff mode. The format of such text can be freely edited. Combine selected texts Select at least two text items and choose this option. It brings up a dialog showing the result for you to edit, e.g., adding space etc. Sometimes special dynamics are entered this way, e.g.,, "sf-mf", entered as "sf" "-" and "mf", should be combined into one text item. Only items in the same voice, the same part and the same measure can be combined. Split text Split current text block into separate ones. A dialog appears, and you can press shift+enter at the position you want to split. Move text Move current text to different voice/part. A dialog will let you scroll through the part+voice to re-place the text. When the same beat position is not available due to note/rest value difference, the text will be shifted backwards to the nearest note/rest. Hyphenation Radio buttons. For long text blocks, hyphenation is required. The options are (English) End of line and (Chinese) Begin of line. Default is EOF, but we must finally recognize Chinese texts and switch to BOF for them automatically. ---------------------------------------- 2.6 Lyrics Management Dialog A dialog showing table like Text management. The layout is: part, lyrics But since the lyrics are long blocks, they will not be displayed completely here. The beginning 5 words will be shown, and when pressing F2, a dialog containing multiple line editbox will appear for you to edit. In the dialog, there are radio buttons to switch between print and braille mode. Context menu Undo/Redo Common undo/redo function. Translation table combo box. Choose a table for current selected lyrics part. Chinese lyrics Checkbox. Chinese lyrics has different format from English one. This will be done later (todo item). Use lyric sign (checkbox, default checked) Toggle lyric sign (dots 5-6 2-3) on/off. Some countries don't use lyric sign. Lyrics position Radio button, put lyric line above/below music. Default is below. Use repetition (checkbox, default checked) If same word(s) are repeated, use repeat signs (one or two dots 3-5's and one 3-5 around the block, or number plus dots 3-5 before and dots 3-5 alone after it, when repetition is more than 3 times). 2.6 Chords Management (to do it later) ---------------------------------------- 2.8 Metronome Dialog This is a list of all metronome marks in the score. ======================================== Chapter 3: Braille Music Editing And Debugging Related Points This chapter discusses braille music editing and correction related subjects. 3.1 GUI specifications The working area of BrailleOrch is an edit window like Windows notepad. Items entered and displayed here are all unicode braille. Untranslatable items such as Chinese characters are displayed as yellow question marks, and in braille output, a set of computer-braille question marks (dots 1-4-5-6). Untagged items such as user-entered customized items are marked as "other" in bmml and displayed in gray. BrailleOrch can also ignore non-fatal musicxml errors, and displays such problematic items in red. Very serious error such as unmatched element tags will generate warnings, and store the xml into .bor file for debugging. Once debugging is finished, it can then be transcribed using Transcribe under Transcription Menu. Items in the edit window must be announced via screen readers such as NVDA. The description should be as brief but clear as possible. Dots should also be announced. Settings of announcing modes are in Options Menu. ---------------------------------------- 3.2 Entering, selecting And Marking Items, transcription related When correcting the music, for example, adding missing signs, moving words' position etc, please press letter n to start entering notes/rests/articulations. BrailleOrch will recognize them automatically. Unfinished enter will be tagged and announced as "other". (Note: make this complicated function later, now just tag all user-entered strings as "other". So reformatting of individual lines must be done manually, like manual transcription.) For moving words, please put cursor on any location within the word block, and right-click, choose "Cut", and paste it to new location. BrailleOrch always treats a word block as a single object. When the cursor is on a part prefix, word block, lyric and chord symbol line, pressing F2 will bring up an edit window for simple modification, without opening corresponding dialogs. You can choose from normal and braille inputs via radio buttons. Note: After editing a part prefix, a confirmation dialog will appear, asking you whether to change the prefix globaly. This is useful when a part switches to another instrument or ensemble changes to solo. In notation programs, sighted engraver only hides part prefix and uses normal text to make such a change, but in braille, we must use corresponding prefix to make things clear. Note to BMML developers: In such case, the partlist will generate an extra sub-element to show a different prefix, from and to which measure. Or we can directly insert such tag within the score itself, like temporary midi instrument changes in Musicxml. Selecting parts This function is copied from notation and sequencing softwares like Sibelius and Sonar. You can use ctrl+, to select parts you want to delete, rename and move globaly. For example, selecting parts 1 (piccolo) and 3 (oboes) and then select measure 5-12, then choose Part management, renaming the prefixes will ask you whether to rename them globally or just for selected measures. This will also ease modification for temporary divisi or instrument changes for multiple parts. Context menu for marking items Besides common edit context items, here are some special ones: Hide/Unhide This is an option for selected objects such as rests, to hide them in braille. For example, a harp glissando with 7 32nd notes to indicate string tuning, and then a gliss line to a note far from them. The intermediate rests can be hidden if the measure has no other notes after this series of notes. If unhide, the rests will be preceded by dot 5. The same thing is applicable for repeated texts which appear for more than one times vertically. For example, a tempo mark will appear on top of both flute and first violin parts, or even all parts. Tagging Change the property of current selected braille character(s). Available choices are text-music, text-non-music, text-title, text-subtitle, text-composer, text-lyricist, lyrics, chords, metronome marks, rehearsal marks, articulation and other. Property This dialog will define the property of current selected character(s). Choices are: isolate, before note and after note. When isolated, a line break can take place on either side of the object; before note will put line break only before it; and after note puts line break only after it. Part/Text/Lyrics/Chords/Metronome management These are the same dialogs introduced before, but only display selected items on-the-fly. When on a specified item, dialogs of other properties will be grayed. Add hand change signs for selected passage This is for piano or other 2-staff music where some hand changes occur on one staff with direction change of stems. This dialog will let you choose which direction is for which hand, and add hand signs into the passage. combining and split There must be a submenu of this. When in post production, sometimes a braille system containing only one measure can be combined to another one, or a multimeasure braille system has to be splitted into two (after adding missing items) in bar-over-bar format, these options are useful. Combine with Placing the cursor to the measure and choose this, will let you choose whether to combine with previous or next measure. A confirmation prompt appears, answer Yes. When in bar-over-bar mode, a warning will appear if the result will make extra line break(s). In line-over-line format, a warning appears if all parts have new line breaks. Choose Cancel to abort. Make new braille system Will start a new braille system from the current measure. A confirmation prompt will appear. Answer Yes. ---------------------------------------- 3.3 Debugging Mode This is a special tool for advanced users or developers to find errors in both Musicxml and BMML. Most of the errors are from incomplete musicxml, or some undeveloped features making BrailleOrch ill. The debugging mode will show errors and let you correct fatal errors on-the-fly. This mode will generate two extra windows linked to the main braille edit window (ctrl+1), one for Musicxml (ctrl+2) and the other BMML (ctrl+3) respectively. Ctrl+tab and shift+ctrl+tab can also cycle among these windows. When navigating in one window, the other two will also be updated. For example, when navigated to a new note in braille, the other two will put the cursor to the first line of this entry. Toolbar: find error (ctrl+F2) Liit all errors in a box to choose. The list shows errors layouted as part-measure-voice-beat. Press OK to jump there. Next error (Ctrl+F5) Previous error (ctrl+F3) Ignore (ctrl+) Mark such item as "other" quickly. In the two xml windows, you can't do any copy/paste functions, but can still enter and delete, for example, correcting or deleting garbage codes (Finale often exports Chinese as garbage codes), and fix mismatched element entry. This way, copyrighted print materials will not be duplicated by end-users (unless he/she has enough time and patience to re-type thousands or millions of xml lines!). For compressed Musicxml files (.mxl), some pieces may contain pictures for either cover pages or unusual music symbols or others. When images are available, there are two ways to access them visually on the screen: 1. Press Ctrl+I in the Musicxml window. If BrailleOrch finds any images, a list will appear, describing filename, part, staff and bar numbers. Choose one and press enter or OK, the picture can display on the screen, and the cursor will locate on the image link code. 2. On a line of image source link, press Ctrl+Alt+I to view this image. ======================================== Chapter 4: Options Dialog Ah, we come to the last chapter, wholy dedicated to the most sophisticated part--Options dialog! This is a multipage dialog, with several category pages dealing with almost all problems with braille music transcription. Settings in this dialog will apply globaly to any imported Musicxml files. 4.1 General Page Default language (combo box) Current English only. More languages will be added later. Show transcription dialog after importing (checkbox, default checked) Whether show transcription dialog before processing Musicxml file. If not, the transcription will be done according to previously defined settings. Open debugging dialog when fatal error occurs (radio button) Yes No Ask me first (default) When serious xml errors are found, the software will automatically open the debugging mode if Yes. You can use find error function to navigate in all 3 windows. In most case, braille window will be empty, so please choose Transcribe in Transcription menu after correction. Workspace color (combo box) White screen black braille (default) Black screen white braille Black screen green braille Black screen blue braille Page setup (button) Bring up Page setup dialog in File menu. ---------------------------------------- 4.2 Transcription Page Translation table (combo box) List out all translation tables for literary braille. Show capital signs (checkbox, default checked) Some countries don't show capital signs. Note that capital signs will always be removed when texts are using word sign prefix (dots 3-4-5). UK metronome format (checkbox, default unchecked) Braille music produced in UK uses a different metronome expression. Instead of note-equals-number, it uses a sequence of stem sign, space, UK equal sign (dots 5-6 2-3-5-6) and number. Signs to be transcribed (button) A dialog list out some signs. Uncheck some of them when transcribing scores for beginners. The signs are: clefs, fingerings, articulations, ornaments, lyrics, and chords. All are checked by default. Use doubling (checkbox, default checked) Apply doubling to articulations, bowings, tremolos etc. Braille repeats (combo box) None Within measure Within and between measures (default) All Use braille repetition signs. All will use measure reference, e.g., 1-8. Since ensemble scores are too complicated, All should not be used. Use repeats across system (checkbox, default checked) In keyboard and vocal scores, this should be checked. In ensemble scores, some countries use full-measure repetition sign when the first measure of the next braille system is the same as the previous measure in previous braille system; while other countries write the measure out verbatimly. Add extra accidentals (combo box) None Voice only (default) Voice and measure For the same altered note in another voice, or a tied altered note in a new measure, add an extra accidental preceded by dot 5. Add extra accidental to octave intervals (checkbox, default checked) When the above combo box is switched to Off, this checkbox will disappear. Add extra tie to new system (checkbox, default unchecked) Some countries have such a custom, to add a reference tie when the tied measure starts at a new system in bar-over-bar/line-over-line formats, or a new section in section-by-section format. Output interval direction description (checkbox, default checked) See this item in Transcription dialog for details. Output part list (checkbox, default checked) This will usually generate new braille page(s) before the first music page. The list will show all parts and braille abbrev names listed and edited in the part tables in Part management dialog. 2-cell indentation for long names is automatic. New line can also be entered by pressing shift+enter in braille input mode in Braille part list table. Output part list option (radio button) On new page (default) Just before music When only keyboard without part name is available, always don't use a new page, just say "keyboard". When there's an solo line above the keyboard, then "solo XX (instrument name) with keyboard accompaniment". ---------------------------------------- 4.3 Single-line Page format (radio button) Continuous Line-based (default) These two radio buttons adjust format of the music. Some countries format it like section-by-section, according to measure amount of every staff in print version. When set to continuous mode, measure numbers will not be shown. Section prefix (combo box) System number only Show system numbers before every section of music. The format is a parenthesised item with "l"+number with number sign. Measure numbers only The same as system number, but with the prefix "b". System and measure numbers (default) Combine the above to into parenthesis, separated by a space. Combine full-measure rests (checkbox) If not checked, multiple full-measure rests will not be combined, leaving every empty bar separated by space. If checked, two or three full-measure rests will be combined without spaces, and more than three full-measure rests will be combined as a number with one whole rest. ---------------------------------------- 4.4 Bar-over-bar Page Extra octave marks (radio button) None New line only All (default) Add octave marks in every measure of a line, no matter whether they are necessary. New line means adding an extra octave mark in the middle of a measure at the beginning of its new line. Different country uses different custom. Keyboard measure number format (combo box) Don't show Left without number sign (default) Left with number sign Left with number sign for only first measure of a print system (a format used by ONCE, Spain, for both piano and ensemble scores) This includes piano, organ and solo with keyboard accompaniment. Full score measure number format (combo box) Don't show Left without number sign Left with number sign Left with number sign for only first measure of a print system Above the system for the first measure (first measure of the braille system, default) Above system for all measures (all measures of the braille system) Above with measure range (for example, 48-49) Show system number (checkbox, default checked) This will put a number (without number sign) before left hand sign (no space) of keyboard music, or put a parenthesized "l"+number item centered above measure number in ensemble score. Rehearsal mark placement (combo box) After part prefix Before part prefix Above music and measure number (default) Above music and left of measure number When the last choice is set, Above system for all measures must be turned to first measure in case of unsufficient room in the line. Add tracking dots (checkbox, default checked) When a line contains 7 and more spaces, tracking dots (dot 3) are added to ease navigation. Some countries don't use them. Multi-piano format (radio button) Piano style (default) Chamber style When transcribing a multi-piano score, there are two different formats. Piano style is to add a lower-celled number after dots 3-4-5 of hand signs (e.g. 4-6 3-4-5 2 and 4-5-6 3-4-5 2 for second piano); chamber style will use the style like orchestral music, showing part prefixes. Use parallel motion (checkbox, default unchecked) Use parallel motion sign for doubled parts. Ensemble score cutoff (combo box) No Yes according to print (default) Yes for all silent instruments This is not applied to keyboard and solo with keyboard accompaniment scores. No will display all staves all the time, Yes according to print will hide silent staves according to settings in Musicxml, and Yes for all silent instruments will hide all silented (rest-only) instruments. If all instruments stop for one or more measures, staves of previously playing parts are shown, or show the ones according to Musicxml's setting. Show all parts on first page (checkbox, default unchecked) Display full part names on first page (checkbox, default unchecked) These two are for ensemble scores. Key signature placement (radio button) Before part prefix After part prefix (default) For scores with parts in different keys, or with transposing instruments with different key signatures. When at the left, all other part names must be shifted right. For scores with the same key in all parts, key signature will be automatically brailled above the system, below measure numbers. Key signature display (combo box) All the time (default) Only once Appear at the beginning of a part or a key change. If Show all parts on first page is checked, they are present at the first page. If not, they will appear at the places where the paqt(s) appear for the first time. Reappear after silence The same as the second one, but will reappear after the instrument staves' cutoff. This option is again for score with transposing instruments. Piano time signature placement (radio button) After part prefixes Above system (default) Full score time signature placement (radio button) After part prefixes (default) Above system Two circumstances will override this setting, and print time signatures always within every part: 1. Different part has different time signature; 2. Time signature changes in the middle of a braille system. Place blank line between keyboard systems (checkbox, default unchecked) Sometimes for easy reading purpose, keyboard and solo with keyboard accompaniment scores are formatted by separating systems using blank line. Place blank line between ensemble systems (checkbox, default checked) Most of the ensemble scores using this custom. Ignore page turnning (checkbox, default unchecked) The first part of a parallel will not be forced to put on a new page if checked. This is for long orchestral music to save paper. Ignore new system (checkbox, default unchecked) By default, both bar-over-bar and line-over-line will start a new parallel when Musicxml starts a new system. Checking this will prevent BrailleOrch from starting a new parallel if there's room for the following measure(s) on next system. In this case, new system number will be moved to the next parallel in keyboard score, while shown above system right at the beginning of new system in ensemble score. If page turn is met, the turning page sign will be brailled at its right place. ---------------------------------------- 4.5 Line-over-line Page The main difference of these two formats is whether to vertically align measures in all staves of the system. In line-over-line, all measures in a system are not aligned, and once there's a staff which doesn't come to line break, other staves can continue with several lines of music. The advantage of line-over-line is saving paper. Most of the settings of bar-over-bar are the same, except the following: Extra octave marks: only None and Yes, Yes equals New line only. Measure number format: no Above system for all measures No Add tracking dots Add Combine full-measure rests checkbox Ignore new system will turn off system number completely. ---------------------------------------- 4.6 Section-by-section Page Section-by-section is used in many countries with varied layouts. Here, I choose some classical features for the users. If anyone who wants a different layout, please contact Daniel Barich for implementation. Indentation (radio button) First line indent (default) Following lines indent These are two main different indentation styles. Line-over-line style (checkbox, default unchecked) Only applicable to keyboard music. The layout is much like line-over-line, but line breaking is free for all staves. Measure number placement for line-over-line style (radio button) Left of music (default) Above system Section head format (radio button) Section only (section number) Measure only (measure number) Section and measure (default, plus number of first measure, no space and number sign. See next control) Section and measure range (section number, space, measure range) These are 4 classical head styles of a section. Section+measure format (radio button) Section uper-celled Measure upper-celled (default) Section+measure range format (radio button) Section uper-celled (default) Measure upper-celled These two numbers are often in different type, one upper-celled while the other lower-celled. Use system number as section number (checkbox, default unchecked) It uses system number on a print page for section number. So if a new page is here, the section number will return to 1. Place blank line between sections (checkbox, default unchecked) See previous explanation. Key signature placement: no Before part prefix Other options of key and time signatures are the same as previous two formats. Braille page turn is ignored, but print system change can't. This ensures the sections to sync to systems in print. Other options are nearly the same as line-over-line, including the Combine full-measure rests. ======================================== Contact Information If you are willing to help us, or want to join in the projecet, please write to Daniel for requesting of adding colleagues into Github, and/or for questions about software development. Daniel's email address is barichd@kenyon.edu. If you have any questions about music, braille and braille music, please write to me at hhpcomposer@gmail.com. Thank you in advance!