From 0f0ae515af4b242e7a3afc9a7631bf0f27f46d87 Mon Sep 17 00:00:00 2001 From: "Tim E. Real" Date: Fri, 22 Feb 2013 06:51:28 +0000 Subject: HTML files --- .../html/single/developer_docs/developer_docs.css | 34 + .../html/single/developer_docs/developer_docs.html | 1745 ++++++++++++++++++++ muse2/doc/html/single/developer_docs/img1.png | Bin 0 -> 853 bytes muse2/doc/html/single/developer_docs/img2.png | Bin 0 -> 374 bytes muse2/doc/html/single/developer_docs/img3.png | Bin 0 -> 476 bytes muse2/doc/html/single/developer_docs/index.html | 1745 ++++++++++++++++++++ muse2/doc/html/single/documentation/arrow_tool.png | Bin 0 -> 258 bytes .../html/single/documentation/documentation.css | 35 + .../html/single/documentation/documentation.html | 1702 +++++++++++++++++++ muse2/doc/html/single/documentation/img1.png | Bin 0 -> 613 bytes muse2/doc/html/single/documentation/index.html | 1702 +++++++++++++++++++ .../single/documentation/main_window_add_track.png | Bin 0 -> 101707 bytes .../single/documentation/main_window_annotated.png | Bin 0 -> 82252 bytes .../documentation/main_window_with_arrangement.png | Bin 0 -> 169229 bytes .../documentation/main_window_with_automation.png | Bin 0 -> 99278 bytes .../main_window_with_midi_automation.png | Bin 0 -> 100858 bytes .../main_window_with_midi_editor_vam.png | Bin 0 -> 130510 bytes .../single/documentation/midi_config_window.png | Bin 0 -> 89152 bytes .../single/documentation/midi_routing_matrix.png | Bin 0 -> 18031 bytes muse2/doc/html/single/documentation/mixer.png | Bin 0 -> 56812 bytes .../single/documentation/mixer_with_one_input.png | Bin 0 -> 31360 bytes .../documentation/mixer_with_one_input_buttons.png | Bin 0 -> 8825 bytes muse2/doc/html/single/documentation/muse2.png | Bin 0 -> 97657 bytes muse2/doc/html/single/documentation/no_audio.png | Bin 0 -> 32195 bytes .../html/single/documentation/output_routing.png | Bin 0 -> 27489 bytes .../single/documentation/project_my_first_song.png | Bin 0 -> 56152 bytes .../html/single/documentation/soloing_window.png | Bin 0 -> 64983 bytes muse2/doc/html/single/documentation/vam_synth.png | Bin 0 -> 75861 bytes .../html/split/developer_docs/developer_docs.css | 34 + .../html/split/developer_docs/developer_docs.html | 113 ++ muse2/doc/html/split/developer_docs/img1.png | Bin 0 -> 853 bytes muse2/doc/html/split/developer_docs/img2.png | Bin 0 -> 374 bytes muse2/doc/html/split/developer_docs/img3.png | Bin 0 -> 476 bytes muse2/doc/html/split/developer_docs/index.html | 113 ++ muse2/doc/html/split/developer_docs/node1.html | 115 ++ muse2/doc/html/split/developer_docs/node10.html | 332 ++++ muse2/doc/html/split/developer_docs/node11.html | 153 ++ muse2/doc/html/split/developer_docs/node12.html | 96 ++ muse2/doc/html/split/developer_docs/node13.html | 79 + muse2/doc/html/split/developer_docs/node14.html | 76 + muse2/doc/html/split/developer_docs/node15.html | 79 + muse2/doc/html/split/developer_docs/node2.html | 111 ++ muse2/doc/html/split/developer_docs/node3.html | 255 +++ muse2/doc/html/split/developer_docs/node4.html | 344 ++++ muse2/doc/html/split/developer_docs/node5.html | 860 ++++++++++ muse2/doc/html/split/developer_docs/node6.html | 82 + muse2/doc/html/split/developer_docs/node7.html | 234 +++ muse2/doc/html/split/developer_docs/node8.html | 125 ++ muse2/doc/html/split/developer_docs/node9.html | 72 + muse2/doc/html/split/documentation/arrow_tool.png | Bin 0 -> 258 bytes .../doc/html/split/documentation/documentation.css | 35 + .../html/split/documentation/documentation.html | 196 +++ muse2/doc/html/split/documentation/img1.png | Bin 0 -> 613 bytes muse2/doc/html/split/documentation/index.html | 196 +++ .../split/documentation/main_window_add_track.png | Bin 0 -> 101707 bytes .../split/documentation/main_window_annotated.png | Bin 0 -> 82252 bytes .../documentation/main_window_with_arrangement.png | Bin 0 -> 169229 bytes .../documentation/main_window_with_automation.png | Bin 0 -> 99278 bytes .../main_window_with_midi_automation.png | Bin 0 -> 100858 bytes .../main_window_with_midi_editor_vam.png | Bin 0 -> 130510 bytes .../split/documentation/midi_config_window.png | Bin 0 -> 89152 bytes .../split/documentation/midi_routing_matrix.png | Bin 0 -> 18031 bytes muse2/doc/html/split/documentation/mixer.png | Bin 0 -> 56812 bytes .../split/documentation/mixer_with_one_input.png | Bin 0 -> 31360 bytes .../documentation/mixer_with_one_input_buttons.png | Bin 0 -> 8825 bytes muse2/doc/html/split/documentation/muse2.png | Bin 0 -> 97657 bytes muse2/doc/html/split/documentation/no_audio.png | Bin 0 -> 32195 bytes muse2/doc/html/split/documentation/node1.html | 146 ++ muse2/doc/html/split/documentation/node10.html | 265 +++ muse2/doc/html/split/documentation/node11.html | 259 +++ muse2/doc/html/split/documentation/node12.html | 75 + muse2/doc/html/split/documentation/node13.html | 222 +++ muse2/doc/html/split/documentation/node2.html | 74 + muse2/doc/html/split/documentation/node3.html | 231 +++ muse2/doc/html/split/documentation/node4.html | 591 +++++++ muse2/doc/html/split/documentation/node5.html | 209 +++ muse2/doc/html/split/documentation/node6.html | 489 ++++++ muse2/doc/html/split/documentation/node7.html | 169 ++ muse2/doc/html/split/documentation/node8.html | 161 ++ muse2/doc/html/split/documentation/node9.html | 173 ++ .../html/split/documentation/output_routing.png | Bin 0 -> 27489 bytes .../split/documentation/project_my_first_song.png | Bin 0 -> 56152 bytes .../html/split/documentation/soloing_window.png | Bin 0 -> 64983 bytes muse2/doc/html/split/documentation/vam_synth.png | Bin 0 -> 75861 bytes 84 files changed, 13727 insertions(+) create mode 100644 muse2/doc/html/single/developer_docs/developer_docs.css create mode 100644 muse2/doc/html/single/developer_docs/developer_docs.html create mode 100644 muse2/doc/html/single/developer_docs/img1.png create mode 100644 muse2/doc/html/single/developer_docs/img2.png create mode 100644 muse2/doc/html/single/developer_docs/img3.png create mode 100644 muse2/doc/html/single/developer_docs/index.html create mode 100644 muse2/doc/html/single/documentation/arrow_tool.png create mode 100644 muse2/doc/html/single/documentation/documentation.css create mode 100644 muse2/doc/html/single/documentation/documentation.html create mode 100644 muse2/doc/html/single/documentation/img1.png create mode 100644 muse2/doc/html/single/documentation/index.html create mode 100644 muse2/doc/html/single/documentation/main_window_add_track.png create mode 100644 muse2/doc/html/single/documentation/main_window_annotated.png create mode 100644 muse2/doc/html/single/documentation/main_window_with_arrangement.png create mode 100644 muse2/doc/html/single/documentation/main_window_with_automation.png create mode 100644 muse2/doc/html/single/documentation/main_window_with_midi_automation.png create mode 100644 muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png create mode 100644 muse2/doc/html/single/documentation/midi_config_window.png create mode 100644 muse2/doc/html/single/documentation/midi_routing_matrix.png create mode 100644 muse2/doc/html/single/documentation/mixer.png create mode 100644 muse2/doc/html/single/documentation/mixer_with_one_input.png create mode 100644 muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png create mode 100644 muse2/doc/html/single/documentation/muse2.png create mode 100644 muse2/doc/html/single/documentation/no_audio.png create mode 100644 muse2/doc/html/single/documentation/output_routing.png create mode 100644 muse2/doc/html/single/documentation/project_my_first_song.png create mode 100644 muse2/doc/html/single/documentation/soloing_window.png create mode 100644 muse2/doc/html/single/documentation/vam_synth.png create mode 100644 muse2/doc/html/split/developer_docs/developer_docs.css create mode 100644 muse2/doc/html/split/developer_docs/developer_docs.html create mode 100644 muse2/doc/html/split/developer_docs/img1.png create mode 100644 muse2/doc/html/split/developer_docs/img2.png create mode 100644 muse2/doc/html/split/developer_docs/img3.png create mode 100644 muse2/doc/html/split/developer_docs/index.html create mode 100644 muse2/doc/html/split/developer_docs/node1.html create mode 100644 muse2/doc/html/split/developer_docs/node10.html create mode 100644 muse2/doc/html/split/developer_docs/node11.html create mode 100644 muse2/doc/html/split/developer_docs/node12.html create mode 100644 muse2/doc/html/split/developer_docs/node13.html create mode 100644 muse2/doc/html/split/developer_docs/node14.html create mode 100644 muse2/doc/html/split/developer_docs/node15.html create mode 100644 muse2/doc/html/split/developer_docs/node2.html create mode 100644 muse2/doc/html/split/developer_docs/node3.html create mode 100644 muse2/doc/html/split/developer_docs/node4.html create mode 100644 muse2/doc/html/split/developer_docs/node5.html create mode 100644 muse2/doc/html/split/developer_docs/node6.html create mode 100644 muse2/doc/html/split/developer_docs/node7.html create mode 100644 muse2/doc/html/split/developer_docs/node8.html create mode 100644 muse2/doc/html/split/developer_docs/node9.html create mode 100644 muse2/doc/html/split/documentation/arrow_tool.png create mode 100644 muse2/doc/html/split/documentation/documentation.css create mode 100644 muse2/doc/html/split/documentation/documentation.html create mode 100644 muse2/doc/html/split/documentation/img1.png create mode 100644 muse2/doc/html/split/documentation/index.html create mode 100644 muse2/doc/html/split/documentation/main_window_add_track.png create mode 100644 muse2/doc/html/split/documentation/main_window_annotated.png create mode 100644 muse2/doc/html/split/documentation/main_window_with_arrangement.png create mode 100644 muse2/doc/html/split/documentation/main_window_with_automation.png create mode 100644 muse2/doc/html/split/documentation/main_window_with_midi_automation.png create mode 100644 muse2/doc/html/split/documentation/main_window_with_midi_editor_vam.png create mode 100644 muse2/doc/html/split/documentation/midi_config_window.png create mode 100644 muse2/doc/html/split/documentation/midi_routing_matrix.png create mode 100644 muse2/doc/html/split/documentation/mixer.png create mode 100644 muse2/doc/html/split/documentation/mixer_with_one_input.png create mode 100644 muse2/doc/html/split/documentation/mixer_with_one_input_buttons.png create mode 100644 muse2/doc/html/split/documentation/muse2.png create mode 100644 muse2/doc/html/split/documentation/no_audio.png create mode 100644 muse2/doc/html/split/documentation/node1.html create mode 100644 muse2/doc/html/split/documentation/node10.html create mode 100644 muse2/doc/html/split/documentation/node11.html create mode 100644 muse2/doc/html/split/documentation/node12.html create mode 100644 muse2/doc/html/split/documentation/node13.html create mode 100644 muse2/doc/html/split/documentation/node2.html create mode 100644 muse2/doc/html/split/documentation/node3.html create mode 100644 muse2/doc/html/split/documentation/node4.html create mode 100644 muse2/doc/html/split/documentation/node5.html create mode 100644 muse2/doc/html/split/documentation/node6.html create mode 100644 muse2/doc/html/split/documentation/node7.html create mode 100644 muse2/doc/html/split/documentation/node8.html create mode 100644 muse2/doc/html/split/documentation/node9.html create mode 100644 muse2/doc/html/split/documentation/output_routing.png create mode 100644 muse2/doc/html/split/documentation/project_my_first_song.png create mode 100644 muse2/doc/html/split/documentation/soloing_window.png create mode 100644 muse2/doc/html/split/documentation/vam_synth.png (limited to 'muse2/doc/html') diff --git a/muse2/doc/html/single/developer_docs/developer_docs.css b/muse2/doc/html/single/developer_docs/developer_docs.css new file mode 100644 index 00000000..d3fede21 --- /dev/null +++ b/muse2/doc/html/single/developer_docs/developer_docs.css @@ -0,0 +1,34 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ +DIV.navigation { } +SPAN.textit { font-style: italic } +SPAN.arabic { } +SPAN.textbf { font-weight: bold } diff --git a/muse2/doc/html/single/developer_docs/developer_docs.html b/muse2/doc/html/single/developer_docs/developer_docs.html new file mode 100644 index 00000000..9cf45e45 --- /dev/null +++ b/muse2/doc/html/single/developer_docs/developer_docs.html @@ -0,0 +1,1745 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + +
+ +

+Contents +

+ + + + +

+Internals - how it works +

+This chapter explains how MusE is built internally, and is meant +to be an aid for developers wanting to quickly start up with MusE. +For details on why stuff is done please refer to the following +chapter. + +

+ +

+User interface programming +

+We use the QT Toolkit for GUI- and other programming. The QT-Assistant +is an important tool for getting help. Almost everything can be looked +up there. + +

+GUIs can be either be hardcoded (see fterfirsta`a=95 _ `a=58 : + `a>64 + `a<91 aaa + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>rranger.cpp for an example) +or can be created using QT-Designer (see the dialogs under +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>idgets/function_dialogs/ for mostly cleanly-written examples). +Don't forget to add your fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>pp, fterfirsth`h=95 _ `h=58 : + `h>64 + `h<91 hhh + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>> and fterfirstu`u=95 _ `u=58 : + `u>64 + `u<91 uuu + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>i files to the +corresponding sections in the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>MakeLists.txt! + +

+Additionally, MusE offers some custom widgets, like menu title items etc. +Following, there will be a small, unordered list about custom widgets: + +

+ +

+ +

+
+Configuration +

+Configuration is a bit pesky in MusE in its current state. If you get +confused by reading this chapter, that's a sign of a sane mind. + +

+There are three kinds of configuration items: + +

+ +

+ +

+Reading configuration +

+fterfirstv`v=95 _ `v=58 : + `v>64 + `v<91 vvv + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>oid MusECore::readConfiguration(Xml&, bool, bool) in +fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp is the central point +of reading configuration. It is called when MusE is started first +(by fterfirstb`b=95 _ `b=58 : + `b>64 + `b<91 bbb + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ool MusECore::readConfiguration()), and also when a +song is loaded. +
It can be instructed whether to read MIDI ports (3), global configuration +and MIDI ports (1+3). Per-Song configuration is always read (2). + +

+When adding new configuration items and thus altering fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration(), +you must take care to place your item into the correct section. The code is +divided into the following sections: + +

+ +

+The sections are divided by comments (they contain --, so just +search for them). Please do not just remove code for reading obsolete entries, +but always add an appropriate entry to the 'skipping' section in order to +prevent error messages when reading old configs. + +

+ +

+Writing configuration +

+Global configuration is written using the +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration() functions, while +per-song-config is written by fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeConfiguration() +(notice the missing fterfirstG`G=95 _ `G=58 : + `G>64 + `G<91 GGG + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lobal; both implemented in fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp). + +

+fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteConfiguration is actually just a subset of the code in +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. Duplicate code! +

+ +

+Song state +

+Additionally to per-song configuration, there is the song's state. +This contains "the song", that is all tracks, parts and note events, +together with information about the currently opened windows, their +position, size, settings and so on. Adding new items here is actually +pretty painless: Configuration is read and written using +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usECore::Song::read and fterfirst:`:=95 _ `:=58 : + `:>64 + `:<91 ::: + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>:write, both implemented in +fterfirsts`s=95 _ `s=58 : + `s>64 + `s<91 sss + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ongfile.cpp. There are no caveats. + +

+ +

+How to add new items +

+When adding global configuration items, then add them into the second +block ("global configuration") in fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration and into +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+When adding just-per-song items, better don't bother to touch the +"configuration" code and just add it to the song's state (there might +be rare exceptions). + +

+When adding global configuration items, make sure you add them into the +correct section of fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration, and into fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+ +

+User controls and automation +

+ +

+Handling user input +

+ +

+Plugins and synthesizers +

+ +

+Overview +

+When the user launches a plugin's GUI, either a MusE-window with +the relevant controls is shown, or the native GUI is launched. MusE +will communicate with this native GUI through OSC (Open Sound Control). +The relevant classes are fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginGui, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase +(in fterfirstp`p=95 _ `p=58 : + `p>64 + `p<91 ppp + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lugin.h) and fterfirstO`O=95 _ `O=58 : + `O>64 + `O<91 OOO + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>scIF (in fterfirsto`o=95 _ `o=58 : + `o>64 + `o<91 ooo + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>sc.h). + +

+If the user changes a GUI element, first the corresponding control is +disabled, making MusE not steadily update it through automation +while the user operates it. Then MusE will update the plugin's parameter +value, and also record the new value. When appropriate, the controller +is enabled again. + +

+ +

+Processing the input, recording +

+Upon operating a slider, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase::setParam is called, +which usually writes the control change into the ringbuffer +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. (fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::apply(), +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::getData() will read this ringbuffer and +do the processing accordingly). Furthermore, fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::recordAutomation +is called, which either directly modifies the controller lists or writes +the change into a "to be recorded"-list (fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents) +(depending on whether the song is stopped or played). + +

+The fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents list consists of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal +items (see fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trl.h), which hold the following data: + +

+It is processed when the song is stopped. The call path for this is: +fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::stopRolling calls fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::processAutomationEvents +calls fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::processAutomationEvents. +This function removes the old events from the track's controller list +and replaces them with the new events from fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>recEvents. In +fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, just all controller events within the recorded +range are erased; in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode, the fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_START +and fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_STOP types of the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal events are used +to determine the range(s) which should be wiped. + +

+ +

+How it's stored +

+Automation data is kept in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continuous (a new control +point results in the value slowly sloping to the new value). +Furthermore, it stores a fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>curVal (accessed by fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>urVal()), +which holds the currently active value, which can be different from the +actually stored value because of user interaction. This value is also +used when there is no stored automation data. + +

+fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::addController and fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>emoveController are used to add/remove whole controller types; the most important functions which +access fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>controller are: + +

+ +

+Whenever a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList has been manipulated, +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChange(Track*) shall be called, +which emits the fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChanged(Track*) +signal in order to inform any parts of MusE about the change (currently, +only the arranger's part canvas utilizes this). + +

+ +

+Enabling and disabling controllers +

+Disabling the controller is both dependent from the current automation +mode and from whether the GUI is native or not. +In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, once a slider is touched (for MusE-GUIs) or +once a OSC control change is received (for native GUIs), the control +is disabled until the song is stopped or seeked. + +

+In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH (and currently (r1492) fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_READ, but +that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the +corresponding control is disabled. Once the slider is released, the +control is re-enabled again. Checkboxes remain in "disabled" mode, +however they only affect the recorded automation until the last toggle +of the checkbox. (Example: start the song, toggle the checkbox, toggle +it again, wait 10 seconds, stop the song. This will NOT overwrite the +last 10 seconds of automation data, but everything between the first +and the last toggle.). For native GUIs, this is a bit tricky, because +we don't have direct access to the GUI widgets. That is, we have no +way to find out whether the user doesn't touch a control at all, or +whether he has it held down, but just doesn't operate it. The current +behaviour for native GUIs is to behave like in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode. + +

+The responsible functions are: fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::oscControl and +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::oscControl for handling native GUIs, +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::ctrlPressed and fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlReleased for MusE +default GUIs and fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::guiParamPressed, +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParamReleased, fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderPressed and +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderReleased for MusE GUIs read from a UI file; +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSlider* obviously handle sliders, while fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParam* +handle everything else which is not a slider. They call +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableController to enable/disable it. + +

+Furthermore, on every song stop or seek, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableAllControllers +is called, which re-enables all controllers again. The call paths for +this are: + +

+ +

+ +

+Design decisions +

+ +

+Automation +

+As of revision 1490, automation is handled in two ways: User-generated +(live) automation data (generated by the user moving sliders while playing) +is fed into fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. Automation data is kept +in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, +that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continous (a new control +point results in the value slowly sloping to the new value). + +

+While fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo can be queried very quickly and +thus is processed with a very high resolution (only limited by the +minimum control period setting), the automation value are expensive to +query, and are only processed once in an audio driver period. +This might lead to noticeable jumps in value. + +

+This could possibly be solved in two ways: + +

+Maintaining a slave control list +

+This approach would maintain a fully redundant slave control list, +similar to fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. This list must be updated +every time any automation-related thing is changed, and shall contain +every controller change as a tuple of controller number and value. +This could be processed in the same loop as fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo, +making it comfortable to implement; furthermore, it allows to cleanly +offer automation-settings at other places in future (such as storing +automation data in parts or similar). + +

+ +

+Holding iterators +

+We also could hold a list of iterators of the single fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists. +This would also cause low CPU usage, because usually, the iterators only +need to be incremented once. However, it is pretty complex to implement, +because the iterators may become totally wrong (because of a seek in the +song), and we must iterate through a whole list of iterators. + +

+ +

+Just use the current data access functions +

+By just using the current functions for accessing automation data, +we might get a quick-and-dirty solution, which however wastes way too +much CPU ressources. This is because on every single frame, we +need to do a binary search on multiple controller lists. + +

+ +

+Feature requests +

+ +

+Per-Part automation and more on automation +

Automation shall be undo-able. Automation shall reside in parts which +are exchangeable, clonable etc (like the MIDI- and Wave-Parts). +Global per-synth/per-audiotrack automation shall also be available, but +this can also be implemented as special case of part automation (one +long part). + +

+ +

+Pre-Rendering tracks +

+ +

+The feature +

+All tracks shall be able to be "pre-renderable". Pre-rendering shall +be "layered". Pre-rendering shall act like a transparent audio cache: +Audio data is (redundantly) stored, wasting memory in order to save CPU. + +

+That is: Each track owns one or more wave-recordings of the length of +the song. If the user calls "pre-render" on a track, then this track +is played quasi-solo (see below), and the raw audio data is recorded +and stored in the "layer 0" wave recording. If the user has any effects +set up to be applied, then each effect is applied on a different layer +(creating layer 1, layer 2 etc). + +

+This means, that also MIDI and drum tracks can have effects (which +usually only operate on audio, but we HAVE audio data because of this +prerendering). + +

+Furthermore, MusE by default does not send MIDI events to the synthesizers +but instead just plays back the last layer of the prerecording (for +MIDI tracks), or does not pipe the audio data through the whole plugin +chain (causing cpu usage), but instead just plays back the last layer. +The hearable result shall be the same. + +

+Once the user changes any parameter (automation data or plugins for +wave tracks, MIDI events or effect plugin stuff for MIDI tracks), +then MusE shall generate the sound for this particular track in the +"old" way (send MIDI data to synthes, or pipe audio data through plugins). +(So that the user will not even notice that MusE actually pre-renderered +stuff.) Either MusE automatically records this while playback (if possible) +or prompts the user to accordingly set up his cabling and then record +it. Or (temporarily) disables prerecording for this track, falling back +to the plain old way of generating sound. + +

+Quasi-solo means: For wave tracks, just solo the track. For MIDI +tracks, mute all tracks which are not on the same synth (channel?), +and mute all note events which are not on the quasi-soloed track. +This causes MusE to still play any controller events from different +tracks, because they might have effects on the quasi-soloed track. (You +can have notes on channel 1 on one track and controller stuff on channel +1 on another track; then you would need quasi-solo to get proper results.) + +

+ +

+Use cases +

+ +

+Saving CPU +

+On slow systems, this is neccessary for songs with lots of, or demanding +(or both) soft synthes / plugins. Even if the synth or plugin is so +demanding that your system is not able to produce sound in real-time, +then with this feature you'll be able to use the synth (this will make +editing pretty laggish, because for a change you need to re-render at +least a part before you can listen to it, but better than being unable +to use the synth at all!) + +

+ +

+Exporting as audio project +

+Using pre-rendering on all tracks, you easily can export your project +as multi-track audio file (for use with Ardour or similar DAWs). +Just take the last layer of each track, and write the raw audio data +into the file, and you're done. (Maybe we are even able to write down +the raw-raw layer0 audio data plus information about used plugins and +settings etc..?) + +

+ +

+Mobile audio workstations +

+You might want to work a bit on your audio projects on your notebook +while you're not at home, not having access to your hardware synthesizers. +Using this feature, you could have pre-recorded the stuff in your studio +before, and now can at least fiddle around with the non-hw-synth-dependent +parts of your song, while still having your full song with you. + +

+ +

+Applying effects on MIDI tracks +

+If you have many physical audio inputs, you might already be able to +apply effect chains on MIDI tracks, by wiring the synthes' audio +outputs to your soundcard's inputs, and applying the effects on +dedicated input tracks you have to create. This requires you to have +expensive hardware, and is pretty complicated, because you need one +additional track per MIDI synth. + +

+This feature allows you to apply effects on single MIDI tracks, and not +only on full MIDI synthes, and doesn't require you to be have that +many physical audio inputs (you need to manually replug your synthes, +however). + +

+ +

+Possible scenarios +

+ +

+Setting it up +

+Create a wave track, MusE will allow you to set or unset prerendering +for every plugin in the plugin rack (recording the actual track is +useless because it would be a plain copy). +Create a MIDI track, MusE will ask you on which physical audio input +your synth is connected. Setting up multiple synthes on one physical +audio in is allowed, see below. + +

+ +

+Pre-rendering stuff +

+When the user presses the "pre-render" button, all tracks which have +been changed since their last pre-rendering will be re-rendered. +If you have multiple hardware synthes set up as they were connected +to one physical audio input port, MusE will prompt you to first plug +the proper cable in. + +

+ +

+Making changes +

+Change a note in a MIDI part, move or delete a part or change automation +parameters. MusE will temporarily disable the pre-rendered information +and instead generate the sound via sending out MIDI events, piping stuff +through effect chains or similar. If you play back the whole song, or +if you manually trigger a re-rendering of a track via the context menu, +MusE will play back the stuff, record it again and re-enable the +pre-rendered information. + +

+ +

+Extensions +

+ +

+Automatic discovery of physical audio connections +

+The user plugs all (or only some) synthes' audio outs into the available +audio inputs, then runs automatic discovery. This will send MIDI events +to each synthesizer, and look on which audio in there's activity. Then +it will assume that the synthesizer is connected to that particular +audio in. Audio ins which show activity before any MIDI events were +sent are not considered, as they're probably connected to microphones +or other noise-generating non-synthes. + +

+ +

+Audio export +

+As described in the Use cases, MusE can allow you to export your song +in some multitrack audio format. + +

+ +

+Cheap/Faked changes +

+For expensive or unavailable synthes, changing the Volume midi controller, +the Pan controller or similar "easy" controllers will not trigger a +complete re-rendering, but instead "fake" the change, by changing +the volume data directly on the recorded wave. This might require some +learning and might even get pretty complicated. + +

+ +

+Intelligent re-recording +

+For tiny changes, MusE shall only re-render the relevant part. If you +change some MIDI notes, then begin re-recording shortly before the +changes, and end re-recording as soon as the recorded stuff doesn't +differ to much from the stuff coming from the synth. Then properly +blend the old recording with the updated part. + +

+ +

+Slotted editors +

+Currently, MusE has the pianoroll editor, drum editor, score editor, +then the controller editor which is inside the pianoroll/drum editor. +All these editors have a very similar concept: the "time axis" is +vertical and (almost) linear, they handle parts, and events are +manipulated similarly. + +

+A unified editor shall be created which allows you to combine different +kinds of editors in one window, properly aligned against each other. +These "different kinds of editors" shall be handled as "slots"; one +unified editor window consists of: + +

+ +

+Each slot contains the following: + +

+ +

+The main window does not show its scroll bar if there is only one slot, +because the slot's scrollbar is sufficient then. + +

+Slots can be added, destroyed, moved around, maybe even merged (if the +slot types allow it); basically, you can compare them with the staves +in the score editor. + +

+The slots shall align against each other, that is, if a score editor +slot displays a key change with lots of accidentials, then all other +slots shall either also display the key change (if they're score slots) +or display a gap. Events which happen at the same time shall be at the +same x-coordinate, regardless which slot they are. + +

+ +

+Controller master values +

+All controllers (MIDI-controllers and also automation controllers) +shall have one set of "master values" which allow you to set a gain and +a bias. Instead of the actual set value, +$\textrm{value} * \textrm{bias}
++ textrm{bias}$ shall be sent to the MIDI device / the plugin. For +controllers like "pan", the unbiased values shall be transformed, that +is, a pan of 64, with +$\textrm{bias}=2$ and +$\textrm{gain}=0.5$, shall +be transformed to 66 (because 64 is actually 0, while 0 is actually -64). +These values shall be set in the arranger and whereever the actual +controller/automation values can be edited. + +

+ +

+Enabled-indicator while recording +

+The MusE-plugin-GUIs shall display a small LED displaying whether a +controller is currently enabled or disabled. By clicking this LED, the +enabled state shall be switched. + +

+Furthermore, there shall be a dedicated window which only lets you switch +enabled/disabled states. This will be useful when using external GUIs +or the MIDI-controller-to-automation feature, to re-enable a controller +when in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode. + +

+ +

+Linear automation editing +

+While holding some modifier key (like shift), operating the MusE-native- +GUI sliders shall only generate control points when clicking and when +releasing the slider. This will result in linear graphs for continous +controllers, and in large steps for discrete controllers (which is in +particular useful for stuff like "which low/high-pass filter type to use"). + +

+Maybe make this behaviour default for discrete controllers? + +

+ +

+
+Symbolic names for MIDI ports +

+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7"). +The mapping between these symbolic names and the hardware port (like +"ALSA midi out port") is stored in the global configuration. + +

+Song files only specify the symbolic names as the ports associated with +their tracks. No information about physical devices/port names, but only +symbolic names are stored in the song file. + +

+This resolves the issues mentioned in 1.2, and also +allows the user to share his pieces with other people: They would only +have to set up that symbolic-to-hardware mapping once (collisions are +unlikely, because an equal symbolic name should usually mean the same +device) and are happy, instead of having to re-map every port +for every song. + +

+


+ + + diff --git a/muse2/doc/html/single/developer_docs/img1.png b/muse2/doc/html/single/developer_docs/img1.png new file mode 100644 index 00000000..85b2087d Binary files /dev/null and b/muse2/doc/html/single/developer_docs/img1.png differ diff --git a/muse2/doc/html/single/developer_docs/img2.png b/muse2/doc/html/single/developer_docs/img2.png new file mode 100644 index 00000000..b5a0cc4b Binary files /dev/null and b/muse2/doc/html/single/developer_docs/img2.png differ diff --git a/muse2/doc/html/single/developer_docs/img3.png b/muse2/doc/html/single/developer_docs/img3.png new file mode 100644 index 00000000..ac4a584a Binary files /dev/null and b/muse2/doc/html/single/developer_docs/img3.png differ diff --git a/muse2/doc/html/single/developer_docs/index.html b/muse2/doc/html/single/developer_docs/index.html new file mode 100644 index 00000000..9cf45e45 --- /dev/null +++ b/muse2/doc/html/single/developer_docs/index.html @@ -0,0 +1,1745 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + +
+ +

+Contents +

+ + + + +

+Internals - how it works +

+This chapter explains how MusE is built internally, and is meant +to be an aid for developers wanting to quickly start up with MusE. +For details on why stuff is done please refer to the following +chapter. + +

+ +

+User interface programming +

+We use the QT Toolkit for GUI- and other programming. The QT-Assistant +is an important tool for getting help. Almost everything can be looked +up there. + +

+GUIs can be either be hardcoded (see fterfirsta`a=95 _ `a=58 : + `a>64 + `a<91 aaa + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>rranger.cpp for an example) +or can be created using QT-Designer (see the dialogs under +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>idgets/function_dialogs/ for mostly cleanly-written examples). +Don't forget to add your fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>pp, fterfirsth`h=95 _ `h=58 : + `h>64 + `h<91 hhh + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>> and fterfirstu`u=95 _ `u=58 : + `u>64 + `u<91 uuu + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>i files to the +corresponding sections in the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>MakeLists.txt! + +

+Additionally, MusE offers some custom widgets, like menu title items etc. +Following, there will be a small, unordered list about custom widgets: + +

+ +

+ +

+
+Configuration +

+Configuration is a bit pesky in MusE in its current state. If you get +confused by reading this chapter, that's a sign of a sane mind. + +

+There are three kinds of configuration items: + +

+ +

+ +

+Reading configuration +

+fterfirstv`v=95 _ `v=58 : + `v>64 + `v<91 vvv + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>oid MusECore::readConfiguration(Xml&, bool, bool) in +fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp is the central point +of reading configuration. It is called when MusE is started first +(by fterfirstb`b=95 _ `b=58 : + `b>64 + `b<91 bbb + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ool MusECore::readConfiguration()), and also when a +song is loaded. +
It can be instructed whether to read MIDI ports (3), global configuration +and MIDI ports (1+3). Per-Song configuration is always read (2). + +

+When adding new configuration items and thus altering fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration(), +you must take care to place your item into the correct section. The code is +divided into the following sections: + +

+ +

+The sections are divided by comments (they contain --, so just +search for them). Please do not just remove code for reading obsolete entries, +but always add an appropriate entry to the 'skipping' section in order to +prevent error messages when reading old configs. + +

+ +

+Writing configuration +

+Global configuration is written using the +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration() functions, while +per-song-config is written by fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeConfiguration() +(notice the missing fterfirstG`G=95 _ `G=58 : + `G>64 + `G<91 GGG + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lobal; both implemented in fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp). + +

+fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteConfiguration is actually just a subset of the code in +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. Duplicate code! +

+ +

+Song state +

+Additionally to per-song configuration, there is the song's state. +This contains "the song", that is all tracks, parts and note events, +together with information about the currently opened windows, their +position, size, settings and so on. Adding new items here is actually +pretty painless: Configuration is read and written using +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usECore::Song::read and fterfirst:`:=95 _ `:=58 : + `:>64 + `:<91 ::: + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>:write, both implemented in +fterfirsts`s=95 _ `s=58 : + `s>64 + `s<91 sss + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ongfile.cpp. There are no caveats. + +

+ +

+How to add new items +

+When adding global configuration items, then add them into the second +block ("global configuration") in fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration and into +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+When adding just-per-song items, better don't bother to touch the +"configuration" code and just add it to the song's state (there might +be rare exceptions). + +

+When adding global configuration items, make sure you add them into the +correct section of fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration, and into fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+ +

+User controls and automation +

+ +

+Handling user input +

+ +

+Plugins and synthesizers +

+ +

+Overview +

+When the user launches a plugin's GUI, either a MusE-window with +the relevant controls is shown, or the native GUI is launched. MusE +will communicate with this native GUI through OSC (Open Sound Control). +The relevant classes are fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginGui, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase +(in fterfirstp`p=95 _ `p=58 : + `p>64 + `p<91 ppp + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lugin.h) and fterfirstO`O=95 _ `O=58 : + `O>64 + `O<91 OOO + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>scIF (in fterfirsto`o=95 _ `o=58 : + `o>64 + `o<91 ooo + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>sc.h). + +

+If the user changes a GUI element, first the corresponding control is +disabled, making MusE not steadily update it through automation +while the user operates it. Then MusE will update the plugin's parameter +value, and also record the new value. When appropriate, the controller +is enabled again. + +

+ +

+Processing the input, recording +

+Upon operating a slider, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase::setParam is called, +which usually writes the control change into the ringbuffer +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. (fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::apply(), +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::getData() will read this ringbuffer and +do the processing accordingly). Furthermore, fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::recordAutomation +is called, which either directly modifies the controller lists or writes +the change into a "to be recorded"-list (fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents) +(depending on whether the song is stopped or played). + +

+The fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents list consists of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal +items (see fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trl.h), which hold the following data: + +

+It is processed when the song is stopped. The call path for this is: +fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::stopRolling calls fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::processAutomationEvents +calls fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::processAutomationEvents. +This function removes the old events from the track's controller list +and replaces them with the new events from fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>recEvents. In +fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, just all controller events within the recorded +range are erased; in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode, the fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_START +and fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_STOP types of the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal events are used +to determine the range(s) which should be wiped. + +

+ +

+How it's stored +

+Automation data is kept in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continuous (a new control +point results in the value slowly sloping to the new value). +Furthermore, it stores a fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>curVal (accessed by fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>urVal()), +which holds the currently active value, which can be different from the +actually stored value because of user interaction. This value is also +used when there is no stored automation data. + +

+fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::addController and fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>emoveController are used to add/remove whole controller types; the most important functions which +access fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>controller are: + +

+ +

+Whenever a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList has been manipulated, +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChange(Track*) shall be called, +which emits the fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChanged(Track*) +signal in order to inform any parts of MusE about the change (currently, +only the arranger's part canvas utilizes this). + +

+ +

+Enabling and disabling controllers +

+Disabling the controller is both dependent from the current automation +mode and from whether the GUI is native or not. +In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, once a slider is touched (for MusE-GUIs) or +once a OSC control change is received (for native GUIs), the control +is disabled until the song is stopped or seeked. + +

+In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH (and currently (r1492) fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_READ, but +that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the +corresponding control is disabled. Once the slider is released, the +control is re-enabled again. Checkboxes remain in "disabled" mode, +however they only affect the recorded automation until the last toggle +of the checkbox. (Example: start the song, toggle the checkbox, toggle +it again, wait 10 seconds, stop the song. This will NOT overwrite the +last 10 seconds of automation data, but everything between the first +and the last toggle.). For native GUIs, this is a bit tricky, because +we don't have direct access to the GUI widgets. That is, we have no +way to find out whether the user doesn't touch a control at all, or +whether he has it held down, but just doesn't operate it. The current +behaviour for native GUIs is to behave like in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode. + +

+The responsible functions are: fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::oscControl and +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::oscControl for handling native GUIs, +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::ctrlPressed and fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlReleased for MusE +default GUIs and fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::guiParamPressed, +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParamReleased, fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderPressed and +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderReleased for MusE GUIs read from a UI file; +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSlider* obviously handle sliders, while fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParam* +handle everything else which is not a slider. They call +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableController to enable/disable it. + +

+Furthermore, on every song stop or seek, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableAllControllers +is called, which re-enables all controllers again. The call paths for +this are: + +

+ +

+ +

+Design decisions +

+ +

+Automation +

+As of revision 1490, automation is handled in two ways: User-generated +(live) automation data (generated by the user moving sliders while playing) +is fed into fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. Automation data is kept +in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, +that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continous (a new control +point results in the value slowly sloping to the new value). + +

+While fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo can be queried very quickly and +thus is processed with a very high resolution (only limited by the +minimum control period setting), the automation value are expensive to +query, and are only processed once in an audio driver period. +This might lead to noticeable jumps in value. + +

+This could possibly be solved in two ways: + +

+Maintaining a slave control list +

+This approach would maintain a fully redundant slave control list, +similar to fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. This list must be updated +every time any automation-related thing is changed, and shall contain +every controller change as a tuple of controller number and value. +This could be processed in the same loop as fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo, +making it comfortable to implement; furthermore, it allows to cleanly +offer automation-settings at other places in future (such as storing +automation data in parts or similar). + +

+ +

+Holding iterators +

+We also could hold a list of iterators of the single fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists. +This would also cause low CPU usage, because usually, the iterators only +need to be incremented once. However, it is pretty complex to implement, +because the iterators may become totally wrong (because of a seek in the +song), and we must iterate through a whole list of iterators. + +

+ +

+Just use the current data access functions +

+By just using the current functions for accessing automation data, +we might get a quick-and-dirty solution, which however wastes way too +much CPU ressources. This is because on every single frame, we +need to do a binary search on multiple controller lists. + +

+ +

+Feature requests +

+ +

+Per-Part automation and more on automation +

Automation shall be undo-able. Automation shall reside in parts which +are exchangeable, clonable etc (like the MIDI- and Wave-Parts). +Global per-synth/per-audiotrack automation shall also be available, but +this can also be implemented as special case of part automation (one +long part). + +

+ +

+Pre-Rendering tracks +

+ +

+The feature +

+All tracks shall be able to be "pre-renderable". Pre-rendering shall +be "layered". Pre-rendering shall act like a transparent audio cache: +Audio data is (redundantly) stored, wasting memory in order to save CPU. + +

+That is: Each track owns one or more wave-recordings of the length of +the song. If the user calls "pre-render" on a track, then this track +is played quasi-solo (see below), and the raw audio data is recorded +and stored in the "layer 0" wave recording. If the user has any effects +set up to be applied, then each effect is applied on a different layer +(creating layer 1, layer 2 etc). + +

+This means, that also MIDI and drum tracks can have effects (which +usually only operate on audio, but we HAVE audio data because of this +prerendering). + +

+Furthermore, MusE by default does not send MIDI events to the synthesizers +but instead just plays back the last layer of the prerecording (for +MIDI tracks), or does not pipe the audio data through the whole plugin +chain (causing cpu usage), but instead just plays back the last layer. +The hearable result shall be the same. + +

+Once the user changes any parameter (automation data or plugins for +wave tracks, MIDI events or effect plugin stuff for MIDI tracks), +then MusE shall generate the sound for this particular track in the +"old" way (send MIDI data to synthes, or pipe audio data through plugins). +(So that the user will not even notice that MusE actually pre-renderered +stuff.) Either MusE automatically records this while playback (if possible) +or prompts the user to accordingly set up his cabling and then record +it. Or (temporarily) disables prerecording for this track, falling back +to the plain old way of generating sound. + +

+Quasi-solo means: For wave tracks, just solo the track. For MIDI +tracks, mute all tracks which are not on the same synth (channel?), +and mute all note events which are not on the quasi-soloed track. +This causes MusE to still play any controller events from different +tracks, because they might have effects on the quasi-soloed track. (You +can have notes on channel 1 on one track and controller stuff on channel +1 on another track; then you would need quasi-solo to get proper results.) + +

+ +

+Use cases +

+ +

+Saving CPU +

+On slow systems, this is neccessary for songs with lots of, or demanding +(or both) soft synthes / plugins. Even if the synth or plugin is so +demanding that your system is not able to produce sound in real-time, +then with this feature you'll be able to use the synth (this will make +editing pretty laggish, because for a change you need to re-render at +least a part before you can listen to it, but better than being unable +to use the synth at all!) + +

+ +

+Exporting as audio project +

+Using pre-rendering on all tracks, you easily can export your project +as multi-track audio file (for use with Ardour or similar DAWs). +Just take the last layer of each track, and write the raw audio data +into the file, and you're done. (Maybe we are even able to write down +the raw-raw layer0 audio data plus information about used plugins and +settings etc..?) + +

+ +

+Mobile audio workstations +

+You might want to work a bit on your audio projects on your notebook +while you're not at home, not having access to your hardware synthesizers. +Using this feature, you could have pre-recorded the stuff in your studio +before, and now can at least fiddle around with the non-hw-synth-dependent +parts of your song, while still having your full song with you. + +

+ +

+Applying effects on MIDI tracks +

+If you have many physical audio inputs, you might already be able to +apply effect chains on MIDI tracks, by wiring the synthes' audio +outputs to your soundcard's inputs, and applying the effects on +dedicated input tracks you have to create. This requires you to have +expensive hardware, and is pretty complicated, because you need one +additional track per MIDI synth. + +

+This feature allows you to apply effects on single MIDI tracks, and not +only on full MIDI synthes, and doesn't require you to be have that +many physical audio inputs (you need to manually replug your synthes, +however). + +

+ +

+Possible scenarios +

+ +

+Setting it up +

+Create a wave track, MusE will allow you to set or unset prerendering +for every plugin in the plugin rack (recording the actual track is +useless because it would be a plain copy). +Create a MIDI track, MusE will ask you on which physical audio input +your synth is connected. Setting up multiple synthes on one physical +audio in is allowed, see below. + +

+ +

+Pre-rendering stuff +

+When the user presses the "pre-render" button, all tracks which have +been changed since their last pre-rendering will be re-rendered. +If you have multiple hardware synthes set up as they were connected +to one physical audio input port, MusE will prompt you to first plug +the proper cable in. + +

+ +

+Making changes +

+Change a note in a MIDI part, move or delete a part or change automation +parameters. MusE will temporarily disable the pre-rendered information +and instead generate the sound via sending out MIDI events, piping stuff +through effect chains or similar. If you play back the whole song, or +if you manually trigger a re-rendering of a track via the context menu, +MusE will play back the stuff, record it again and re-enable the +pre-rendered information. + +

+ +

+Extensions +

+ +

+Automatic discovery of physical audio connections +

+The user plugs all (or only some) synthes' audio outs into the available +audio inputs, then runs automatic discovery. This will send MIDI events +to each synthesizer, and look on which audio in there's activity. Then +it will assume that the synthesizer is connected to that particular +audio in. Audio ins which show activity before any MIDI events were +sent are not considered, as they're probably connected to microphones +or other noise-generating non-synthes. + +

+ +

+Audio export +

+As described in the Use cases, MusE can allow you to export your song +in some multitrack audio format. + +

+ +

+Cheap/Faked changes +

+For expensive or unavailable synthes, changing the Volume midi controller, +the Pan controller or similar "easy" controllers will not trigger a +complete re-rendering, but instead "fake" the change, by changing +the volume data directly on the recorded wave. This might require some +learning and might even get pretty complicated. + +

+ +

+Intelligent re-recording +

+For tiny changes, MusE shall only re-render the relevant part. If you +change some MIDI notes, then begin re-recording shortly before the +changes, and end re-recording as soon as the recorded stuff doesn't +differ to much from the stuff coming from the synth. Then properly +blend the old recording with the updated part. + +

+ +

+Slotted editors +

+Currently, MusE has the pianoroll editor, drum editor, score editor, +then the controller editor which is inside the pianoroll/drum editor. +All these editors have a very similar concept: the "time axis" is +vertical and (almost) linear, they handle parts, and events are +manipulated similarly. + +

+A unified editor shall be created which allows you to combine different +kinds of editors in one window, properly aligned against each other. +These "different kinds of editors" shall be handled as "slots"; one +unified editor window consists of: + +

+ +

+Each slot contains the following: + +

+ +

+The main window does not show its scroll bar if there is only one slot, +because the slot's scrollbar is sufficient then. + +

+Slots can be added, destroyed, moved around, maybe even merged (if the +slot types allow it); basically, you can compare them with the staves +in the score editor. + +

+The slots shall align against each other, that is, if a score editor +slot displays a key change with lots of accidentials, then all other +slots shall either also display the key change (if they're score slots) +or display a gap. Events which happen at the same time shall be at the +same x-coordinate, regardless which slot they are. + +

+ +

+Controller master values +

+All controllers (MIDI-controllers and also automation controllers) +shall have one set of "master values" which allow you to set a gain and +a bias. Instead of the actual set value, +$\textrm{value} * \textrm{bias}
++ textrm{bias}$ shall be sent to the MIDI device / the plugin. For +controllers like "pan", the unbiased values shall be transformed, that +is, a pan of 64, with +$\textrm{bias}=2$ and +$\textrm{gain}=0.5$, shall +be transformed to 66 (because 64 is actually 0, while 0 is actually -64). +These values shall be set in the arranger and whereever the actual +controller/automation values can be edited. + +

+ +

+Enabled-indicator while recording +

+The MusE-plugin-GUIs shall display a small LED displaying whether a +controller is currently enabled or disabled. By clicking this LED, the +enabled state shall be switched. + +

+Furthermore, there shall be a dedicated window which only lets you switch +enabled/disabled states. This will be useful when using external GUIs +or the MIDI-controller-to-automation feature, to re-enable a controller +when in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode. + +

+ +

+Linear automation editing +

+While holding some modifier key (like shift), operating the MusE-native- +GUI sliders shall only generate control points when clicking and when +releasing the slider. This will result in linear graphs for continous +controllers, and in large steps for discrete controllers (which is in +particular useful for stuff like "which low/high-pass filter type to use"). + +

+Maybe make this behaviour default for discrete controllers? + +

+ +

+
+Symbolic names for MIDI ports +

+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7"). +The mapping between these symbolic names and the hardware port (like +"ALSA midi out port") is stored in the global configuration. + +

+Song files only specify the symbolic names as the ports associated with +their tracks. No information about physical devices/port names, but only +symbolic names are stored in the song file. + +

+This resolves the issues mentioned in 1.2, and also +allows the user to share his pieces with other people: They would only +have to set up that symbolic-to-hardware mapping once (collisions are +unlikely, because an equal symbolic name should usually mean the same +device) and are happy, instead of having to re-map every port +for every song. + +

+


+ + + diff --git a/muse2/doc/html/single/documentation/arrow_tool.png b/muse2/doc/html/single/documentation/arrow_tool.png new file mode 100644 index 00000000..1ae872fb Binary files /dev/null and b/muse2/doc/html/single/documentation/arrow_tool.png differ diff --git a/muse2/doc/html/single/documentation/documentation.css b/muse2/doc/html/single/documentation/documentation.css new file mode 100644 index 00000000..17bee66c --- /dev/null +++ b/muse2/doc/html/single/documentation/documentation.css @@ -0,0 +1,35 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ +DIV.navigation { } +DIV.center { } +SPAN.textit { font-style: italic } +SPAN.arabic { } +SPAN.textbf { font-weight: bold } diff --git a/muse2/doc/html/single/documentation/documentation.html b/muse2/doc/html/single/documentation/documentation.html new file mode 100644 index 00000000..b24ff0be --- /dev/null +++ b/muse2/doc/html/single/documentation/documentation.html @@ -0,0 +1,1702 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + +
+ +

+
+ +
Image muse2 + +
+
+ +

+Contents +

+ + + + +

+What is this? +

+You are, if you have printed this document, holding in your hand the +written documentation for the audio and midi sequencer MusE version 2. +
http://www.muse-sequencer.org is MusE's home on the internet where +everything MusE releated should be possible to find, software, this +documentation, forums, mailing lists, bug reporting, FAQs. If you have +this document but not the software head on over there to find what it's +all about. + +

+User's manual +

+ +

+ +

+Introduction +

+ +

+A brief history of computer audio and MusE +

+To quickly summarize over a decades open source development: in 1999 Werner + Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first +few releases (actually not few, Werner relentlessly churned out new releases) +MusE was only a midi sequencer. The target was to create a fully fledged +midi sequencer for the Linux operating system. Over the years audio was +added among with other things implemented and sometimes abandoned. +Today MusE is a stable and feature rich music creation environment which +strives to encompass most of the music recording process, creation, editing, +mastering. + +

+ +

+Definitions +

+CTRL refers to the control key on the keyboard, e.g. CTRL+C +means to press and hold the control key while pressing the c key. Make sure +you know where you have it so you won't accidentally lose control +(bad jokes are the best jokes, so say we all!). +
SHIFT refers to the shift key on the keyboard, see above for usage +
ALT refers to the alt key on the keyboard, see above for usage +
$> is used as a generic definition for a terminal prompt. When the +manual lists a command that shall be typed, the prompt is not part of the +command. +
+Keys are always referred to in bold uppercase, e.g. A. For instance +SHIFT+A for the key a pressed together with the shift key. +
+Sometimes terminal examples are written tabbed in with a fixed font to +visualize more closely what something looks like on the screen. +E.g. +
$> muse2 +
+

+ +

+Getting up and running for impatient people +

+Install MusE from the repository of your chosen distribution. +To get decent performance start http://jackaudio.org/Jack with +the following command in a terminal: +
$> jackd -d alsa -d hw:0 -p 256 +
+Or, if you prefer, use the launcher utility +http://qjackctl.sourceforge.net/QJackCtl to get some +help starting Jack. +After this, start MusE from the menu or fire up another terminal and +type + +

+muse2. +
+If this didn't work out read on for the slightly more complete route for +getting things started. + +

+ +

+Getting up and running +

+ +

+Installation from binaries +

+There are several ways to install MusE depending on your situation. The +most convenient way is to install a prepackaged version from your chosen +distribution. The drawback of this is that it may not be the most recent +version, though often there is a more recent package from a private packager. + +

+Installation from source +

+Building MusE from source is not hard, there are a number of prerequistes +that must be met but the actual building should be painless (ha, famous +last words). +
+Please follow the README in the source package and/or read the instructions +on the homepage: http://muse-sequencer.org/index.php/Installation +

+ +

+Hardware +

+MusE on the Linux platform supports midi through ALSA and Jack-midi and audio +through Jack. For information on what hardware is supported there are some +convenient places to check: + + +Also, as is often a very good approach for Linux and open source, the +various forums available on the internet often contain good information. +Chances are someone has already tried your configuration and/or had your +specific problem and the solution is already written down. + +

+Launching +

+After installation the binary muse2 is installed on the computer. If MusE +was installed from a distribution repository the binary may have a +different name depending on the distribution policies. Most distributions +do however install a menu entry so MusE should be conveniently available +from there. + +

+Audio preconditions +

+In the standard case MusE expects to find and connect to the Jack audio +server http://jackaudio.org. Make sure jack is installed (if MusE was +installed with a distribution-package Jack will very likely already be +installed) For Jack to run with best performance your system should be +sufficiently tuned to allow it to run with realtime capabilities. The +realtime configuration is configuration of the operating system and roughly +consists of two parts. + +
    +
  1. By default on most distros only the superuser lets applications setup +realtime capabilities. Please see the APPENDIX for setting up realtime +
  2. +
  3. Maximizing performance. A standard linux installation may not able +to reach the performance required by a power user. This requires exchanging +the linux kernel for a so called lowlatency kernel, this is also covered by +the realtime APPENDIX. +
  4. +
+ +

+ +

+Running MusE +

+Find MusE in the menu or open a terminal and enter muse2. + +

+$> muse2 +
+A splash screen should pop up followed +by the main application window and you are off! +
+If an error like the screenshot below pops up the Jack audio server is +either not running or started as a different user than what you are trying +to start MusE as. + +

+ + + +
Figure 2.1: +Jack server missing
+
+ +
Image no_audio
+
+ +

+Midi only +

+MusE can be started in Midi-only mode where MusE does not have any external +dependencies apart from ALSA midi. In this case start MusE from a terminal: +$> muse2 -a + +

+ +

+ALSA midi with Jack +

+If Jack is running, by default MusE will not use ALSA devices, preferring +Jack midi instead. To force ALSA devices to be used as well as Jack +midi, start MusE with the -A option: $> muse2 -A + +

+ +

+Beginners tutorial +

+To get a quick grip of what MusE can achieve please follow this beginners +tutorial. + +

+Midi Setup +

+First off, fire up MusE as was described in the previous chapter, making +sure that the jack audio server is started with sufficient configuration +to allow for audio output without breakup. Also make sure your system can +make sound. + +

+Soft synth test +

+With MusE up and running right click in the Track-pane (see +Fig. 2.8) and select +Add Synth > MESS > vam soft synth. +A Soft Synth track called vam-0 should appear as well as a separate GUI +for the synthesizer. + +

+Now right click once more in the Track-pane and select Add Midi +Track. Another track appears called Track 1, and its track list Port +column should show it is bound to the synth that was just created vam-0. +If it is not, click on the Track 1 Port column to open a drop-down list +of available devices and choose vam-0. + +

+ +

+r0.05 +Image arrow_tool + +
+Now select the drawing tool icon +from the toolbar, alternatively press the shortcut key D. +Move the mouse over to the arranger canvas as referenced in +Fig. 2.8 +and point at the midi track, the mouse should have changed to a small pencil. +Draw a Part along the midi track using the mouse. For this exercise it is +not important where or how large the drawn Part is. When you are done double +click on the drawn part. This will open up the Piano Roll editor. To the +left of the Piano Roll there are piano keys in a vertical line, try clicking +on the keys in this virtual keyboard each click should be rewarded with a +synth sound (maybe of questionable quality, a sound nevertheless) + +
+ + + +
Figure 2.2: +vam synthesizer
+
+ +
Image vam_synth
+
+ +

+ +

+Missing sound +

+If you got sound from the previous exercise you can carry on to the next, +or keep reading for further enlightenment in case you come upon trouble +later on. If there is no sound we need to do some fault hunting. First +off, click on Arranger window once more and select the vam-0 track in the +track-pane. + +
+ + + +
Figure 2.3: +Midi editor view
+
+ +
Image main_window_with_midi_editor_vam
+
+Now bring back Piano Roll window and align the windows so you +can see the piano keys as well as the Meter on the Mixer Strip (see the +5 Function by function chapter for more information on these windows). +The result should be something like the following: + +

+When pressing one of the keys on virtual Keyboard the Meter on the Mixer +Strip should light up in green to visualize that the Synth is making +sound, if it is not try to trace back your steps and and see if you did +anything differently than described. +Now, if the Meter lights up but there is still no sound we need to +check the routing between the tracks. Click on the Arranger window again +and select the Out 1 track, this is the predefined output which MusE by +default loads at startup, at the bottom of Mixer Strip there are two +buttons looking like tele- jacks, these bring up the inputs and outputs +of the track, click on the right one, the output and make sure that it is +connected to some valid outputs on your system. + +

+r0.25 +Image output_routing + +
+Click on the outputs to select them, if you did changes here go back and +try clicking on the Piano Roll keyboard again, hopefully it helped. If there +still are problems make sure your system actually can make sound through +Jack, this is however getting outside the scope of this manual. +
+
This might be the time to bring up the concept of community support. +Open source software could never be what it is without the support given by +individuals on forums and mailinglists, if the information given in this +document is not enough, try googling your problem and/or get in touch with +one of the online forums for MusE or Linux audio in general. See some pointers +in the Support chapter. + +

+ +

+Recording Midi +

TBD + +

+Recording Audio +

+At this point we'll make a a slight detour into full on audio recording. Getting +audio out of MusE has already been covered in the previous chapters so we will +concentrate on the additional steps needed to record onto an audio track. +
+
+When MusE is first fired up, the +output track has already been created (more about this in the chapter about +templates), to proceed with audio recording we need to add two additional tracks, a +wave track and an input track. +
+When MusE is first started right click in an empty space on the track view + +
+ + + +
Figure 2.4: +Add track
+
+ +
Image main_window_add_track
+
+and select Add Audio Input. Right click again and also select +Add Wave Track. Two additional tracks are now visible in the Arranger, +"Input 1" and "Track 1", bring up the mixer with F10 and you should see +the following configuration. + +
+ + + +
Figure 2.5: +Mixer with one input
+
+ +
Image mixer_with_one_input
+
+ +
+Note the buttons on each mixer strip. hover over them to see their +functionality. For more information on all the buttons see coming chapters +about the mixer. For now lets just do what we must. +
+1. click on the stereo symbol over the slider to change the input to a mono track. +
+2. do the same for the wave track (optional) +
+3. click on the Mute (gray speaker) icon on the input track to unmute it. +
+4. click on the input routing button (see the tooltip, it looks like a tele plug) +on the input track and select an appropriate connection from your system. +
+5. click on the output routing button on the input track and select +Track 1 +
+
+Already after the meter on the input track should be able to display that there +is incoming sound from your sound source. If there actually is sound coming +from your sound source, that is. +
+We are now nearly ready to start recording. First we need to select a location +to store the files. MusE does not use a centralized storage of soundfiles but +uses the path of the song-file (extension .med) as guidance as to where the +audio files should be placed. Now as it happens MusE will prohibit us from +starting a recording until the songfile has been stored. So lets take advantage +of this behaviour and just go ahead and try to record. Let's get started. +
+In the mixer click on the red record dot on the Audio Track to arm it +for recording (or enable if you will). Now when there is audio coming into the +input it will also show up on the Audio Track. Also note that all the input and +output routing buttons on the tracks now have the same gray color, this means +that all of the tracks have a proper connection. + +
+ + + +
Figure 2.6: +Mixer buttons
+
+ +
Image mixer_with_one_input_buttons
+
+ +
+All fine and dandy. Now bring up the arranger window and find the round, red on +white record button and click on it. This is your queue to MusE to +prepare for recording. However since we have not saved our song we are presented +with a dialog to do just that. +
+
+ + + +
Figure 2.7: +Save song
+
+ +
Image project_my_first_song
+
+Note the check box for creating a project folder, when working with audio this +is very much recommended or you may soon loose track of what audio files belong +to which song. +
+Finally we are ready to start recording! The process is completed by clicking +on the Play button in the Arranger. If all went well MusE then starts +to record a wave file from the Input Track placed in your song directory. +
+When you wish to stop recording press Stop in the Arranger, now the +resulting waveform should be visible in the Arranger. After rewinding the Play +position and pressing Play again the resulting sound should be audible +through the connected output. + +

+ +

+Basic overview +

+In this section we will make a step by step walk-through of all the +different editors, their purpose and what functions they support. + +

+ +

+Main/Arranger +

+ +

+ + +

+ + + +
Figure 2.8: +MusE main window
+
+ +
Image main_window_annotated
+
+Above is the main window of MusE, the Arranger, this is what greets you +when launching MusE. The Arranger consists of two main parts, the Track-pane +and the Arranger canvas. The Track-pane lists all currently visible tracks +and the Arranger canvas contains all Parts of the composition. The +screenshot above shows an empty project. Below is MusE with a song in +progress, turns out it wasn't a very good song, but for our purposes it +is fine. In the below screenshot there are a lot of tracks visible in the +Track-pane, each have an icon which indicate it's type, wave-track, input, +output etcetera, more about that later. In the Arranger canvas a number of +parts are visible, the ones in yellow are in this composition wave files, +the multicolored line are different Parts of a drum track. + +

+ +

+ + + +
Figure 2.9: +MusE main window with arrangement
+
+ +
Image main_window_with_arrangement
+
+ +

+ +

+
+Mixer +

+Choosing View > Mixer A or B from the menu in the main +window will bring up the mixer as viewed below. The mixer will open with +all options enabled, showing channel strips for all tracks in the current +setup, depending on how far you have gotten this view may become very large, +at which point it may be a good idea to limit what is viewed in the Mixer. +From the view menu all the different kinds of tracks can be toggled on/off +from the mixer. Some may find it a good idea to use the two mixers A and B +setup with different setup and store this in your song template(s), more +about this in the Song Template section. It can be argued that everything +in MusE is a track analogous to the Unix idiom that everything is a file. +The types of tracks visible in the mixer (and track-pane) are: + +
+r0.5 +Image mixer + +
+ + + +

+There is also a Midi Track variation called Drum Track, they are +however not distinguishable from Midi Tracks in the Mixer. Also the +strips for midi tracks are different in the Mixer than in the +Track-pane view. + +

+ +

+Tracks and parts +

+MusE arranges your music in tracks and parts. The following +section shall provide you an overview of how things are done with MusE. +If you are or were a Cubase or Cakewalk user, you will feel familiar with +this. + +

+ +

+Tracks +

+There are two general classes of tracks: MIDI tracks and audio +tracks. MIDI tracks (and drum tracks which are internally MIDI tracks) +can hold note data. The Wave track is a type of audio track which holds +wave data. There are also several other kinds of audio tracks. + +

+ +

+MIDI tracks +

+MIDI and drum tracks hold MIDI event data. They don't differ much, +except that drum tracks offer a special editor which is more suitable +for drum editing. + +

+ +

+Wave tracks +

+They hold audio data which can be just played back or be piped through +effect plugin chains. They offer automation for these plugins. + +

+ +

+Audio input tracks +

+These provide the path for your audio data from outside into your +project. Set up the physical audio inputs you want to connect your +audio input track with, and then route the input tracks to various +other tracks such as wave tracks. + +

+ +

+Audio output tracks +

+These provide the path for your project's audio data to outside. Set +up the physical audio outputs you want to connect your audio out track +with, and then route various other tracks, such as wave tracks, to +the output tracks. + +

+ +

+Audio group tracks +

+Group tracks are like busses, where you can route other tracks to +them, then route the groups to other tracks. Since group tracks have +all the features of other audio tracks, like volume and pan, they +provide a convenient common routing point where you have control of +the sound before it is passed to other tracks. + +

+ +

+
+Audio aux tracks +

+These provide a more convenient way to mix several audio tracks +together. With each audio aux track added, other audio tracks will +gain a common send knob for adjusting the level sent to the aux +track. This can be more convenient than using several group tracks. + +

+ +

+Synthesizer tracks +

+This type of track is a software synthesizer which MIDI and drum tracks +can be assigned to. + +

+ +

+Creation +

+You can create a track by either right-clicking in the arranger's track list and then adding the desired track, or via the edit menu. + +

+ +

+Attributes +

+Tracks have several attributes: +
+
Mute:
+
If you click on the Mute field (denoted with +a "M" column header), the track gets muted and stops producing sound. +
+
Solo:
+
The solo button ("S" column +header) singles out a track for listening. It mutes +some other tracks but may phantom solo others. +For more info see the section on soloing: 2.5 and +phantom soloing: 2.5.1 +
+
Record:
+
The R column "arms" your track for recording. +When you rec-arm your song and have no tracks rec-armed, you won't be +able to record anything. See also the config option "move rec-arm with selection". +
+
Track name:
+
Double-click to edit the track name. +
+
Port:
+
For MIDI tracks, this lets you select the MIDI +port to which the events should be routed. This can be your physical +synthesizer or a software synthesizer. For soft synths, this is the +port the synth is associated to. For other track types, this is disabled. +
+
Channel:
+
For MIDI tracks, this is the MIDI channel the +output is sent to. For any kind of audio tracks, this is the number of +channels (mono, stereo). +
+
Automation:
+
For audio tracks, +this lets you set up the automation display in the arranger. +(See automation 2.7.1). Clicking this will provide you +with a popup menu with lots of submenus. Clicking on a submenu will +select or unselect it showing or hiding the automation parameter as a +graph overlaid on top of the track. +
+The submenus let you select the color you want to associate with the +automation parameter. There you can also assign midi controllers to +the parameters, a dialog is shown where you can manually choose the +midi controller, with a learn button to 'listen for' and +automatically recognize any midi controller operated by you. + +

+

+
Clef:
+
For MIDI tracks, you can specify a clef here. This +only affects the score editor. + +

+

+
+ +

+ +

+The trackinfo side bar +

+In the arranger and the part editors, you'll have a trackinfo sidebar +on the left side. You can set up track-type specific things there. + +

+ +

+
+MIDI trackinfo sidebar +

+The MIDI trackinfo sidebar lets you change program, volume, pan and +more. This sidebar can also be viewed at the left of the pianoroll +editor. + +
+Old style drum tracks: +
+These are MIDI tracks as well, but with a few differences. They allow +you to map certain drum sounds with different input notes, and you +can change the output settings of a certain "drum instrument" without +having to alter each single event. + +

+However, they have certain limitations: They only can handle 128 sounds +(even if you have more synthes), they aren't really compatible with +MIDI tracks (you can interchange parts between them, but if you touched +the drum list, you'll get unexpected results), you can't set a program +for the used channel and more. + +

+ +

+New style drum tracks +

+Because of these limitations, we introduced the new-style drum tracks. +They're not fully compatible with the old drum tracks, so the old are +still retained. Under "Global Settings", "GUI settings", you can set +up whether you prefer the old or new. + +

+They are handled exactly like plain MIDI tracks (staying compatible with +them), and offer all of the functionality, though in a different way. +They allow you to re-order the drum map efficiently, you can open parts +from multiple drum tracks in one drum editor (MusE will separate +the sounds from different tracks according to your settings, see the +"Window Config" menu), and you can set programs as with normal MIDI tracks. + +

+ +

+MIDI trackinfo controls: +
+
+
Output port:
+
This drop-down list selects the midi port +to send midi output from this track. +
+
Output channel:
+
This box selects the midi channel to be +used on the output port. +
+
Input and output routing:
+
Selects midi ports and +channels to receive midi from, and soloing paths. (See Routes +2.4). +
+
Midi through:
+
This button selects whether midi input is +passed through to the selected output port. +
+Depending on your midi devices and settings, there are cases when +this should be off such as using the same port and channel for +input and output (otherwise a double-note echo will be heard), +and cases when it must be on such as when using a synthesizer track +as output device. +
+
Input detect indicator:
+
Blinks when midi activity is +detected on the selected midi channels on the selected midi input +ports. +
+
Transpose:
+
This transposes midi input notes up or down +in pitch. This is very useful if your midi keyboard hasn't enough +keys or the selected output device plays an octave too low or high, +and you would like to shift the octave of the incoming notes to +compensate. +
+
Delay:
+
Adjusts the delay of the notes. +
+
Length:
+
Adjusts the length of the notes. +
+
Velocity:
+
Adjusts the velocity of incoming notes. +Use it to compensate for a too-loud or too-soft keyboard. +
+
Compression:
+
Adjusts the compression of incoming note +velocities. Use it to make soft incoming notes louder, and loud +notes not so loud. +
+
Instrument:
+
Selects the midi instrument patch to be used +by the selected output port. This is equivalent of dialing the patch +in the bank and program boxes, except it displays a more friendly +patch name as defined by the selected output port's midi +instrument. See instruments, or port configuration +2.8.1 +
+
H-Bank:
+
Selects the high bank number of the current patch. +
+
L-Bank:
+
Selects the low bank number of the current patch. +
+
Prog:
+
Selects the program number of the current patch. +
+
Volume:
+
Adjusts the midi volume controller. +
+
Pan:
+
Adjusts the midi pan controller. +
+
+The buttons beside the Prog, Volume, and Pan boxes store the value, +at the current transport position, for midi automation. (See +automation 2.7.1). + +

+Note that the 'Prog' button stores H-Bank and L-Bank along with +'Prog' value, so there are no H-Bank and L-Bank buttons. + +

+The 'All' button simply stores all three Program (and banks), Volume, +and Pan values at once. + +

+Tip: If the Song Type is GM, GS, or XG, you may need to store +desired values at transport position zero, otherwise your adjustments +may be overriden by the instrument when the transport is moved back +to position zero. If this behaviour is undesired, you can set the +Song Type to 'NO' meaning no song type. + +

+ +

+Audio trackinfo sidebar +

+Unlike the midi trackinfo sidebar, the audio trackinfo side bar +is nothing more than an embedded audio mixer strip, the exact same +strip as found in the mixers. (See mixer 2.2.2). + +
+Effects rack: +
+On the top of the audio trackinfo sidebar, there is an effects rack +which allows you to apply various plugins on the audio. For more +information on this, refer to 2.6.1. + +

+ +

+Parts +

+Within MIDI, drum and wave tracks, you can create parts. Parts +are chunks of coherent notes or wave data which can be moved around, +copied, cloned and deleted independent from other parts. + +

+Parts are created by selecting the pencil tool and then drawing onto +the right part area in the arranger. You can move them with the arrow +tool, delete them using the DEL key, and a right-click opens +a popup menu. This menu allows you even more stuff, such as setting +the part's color, saving the part to disk etc.. You can use +CTRL+C and CTRL+V for copying and pasting parts. +CTRL+B pastes the part as a clone. Pressing SHIFT +additionally provides you a dialog which allows you to paste the part +multiple times and set more stuff. + +

+You can also copy parts with the mouse by moving the part with the mouse +while holding down the CTRL key. + +

+ +

+
+Routes +

+Routes are how tracks are connected together and to the outside world. +(They are also how Jack midi ports connect to the outside world. See +midi port configuration 2.8.1). +Each track strip has two buttons whose icons look like plugs. One button +is for input routing and the other is for output routing. Clicking on +these buttons will pop up a menu of available input or output routes that +you can connect to. Most audio tracks list other tracks to connect to, +but audio input and output tracks are special: Audio input track input +routing menus list available Jack audio input ports. Conversely audio +output track output routing menus list available Jack audio output ports. + +

+ +

+r0.25 +Image output_routing + +
+ +

+Meanwhile MIDI and drum tracks allow you to route available MIDI ports +and channels to the track using a handy popup matrix. + +

+ +

+r0.25 +Image midi_routing_matrix + +
+ +

+ +

+
+Anti circular routing +

+Any routing menu item which would cause a circular routing condition +is grayed out. Find out why the condition would exist by examining +routing paths involved and correct the situation if required. + +

+Also, you cannot use a track's aux sends if the track has an input +route path from ANY Aux Track. (See aux tracks 2.3.1). +Aux send knobs and labels are disabled in that case. + +

+ +

+
+Soloing chain routes +

+Soloing chains (see solo chains 2.5.2) are really just +routes like any other. The available solo chaining paths are displayed +in the routing popup menus. + +

+ +

+
+Track soloing +

+Soloing allows you to single out a track for listening while muting others, +without you having to mute the other tracks. (See soloing track attribute +2.3.1). + +

+ +

+
+Phantom soloing +

+In order to solo a track and mute others so that it is heard, MusE +employs 'phantom' soloing: When a track is soloed, MusE automatically +solos all tracks routed to and from this track. (See routes +2.4). A phantom soloed track is indicated by a black square +in the track pane solo column. (See track attributes +2.3.1). + +

+ +

+ + + +
Figure 2.10: +Soloing, with phantom soloing
+
+ +
Image soloing_window
+
+ +

+ +

+
+Soloing chains +

+When an audio output track sends audio to some external entity, such +as an external running application, and audio from the external entity +is fed back into a MusE audio input track, solo chains allow you to +solo the input or output, and MusE will complete the path automatically +soloing the other, and all paths that came before or after it. + +

+Solo chains also work with MIDI tracks chained to audio inputs: +When a MIDI track drives some MIDI device whose audio is fed into MusE, +solo chains allow the entire chain to be soloed. + +

+Solo chains are accessed via routing menus. (See solo chain routes +2.4.2). + +

+ +

+
+Plugins +

+Plugins are small add-ons which can process a track's data. + +

+MIDI plugins operate on midi and drum tracks, and are found in +the Midi menu. + +

+Audio plugins can be applied to any track handling audio (that is, +inputs, outputs, wave tracks, synth tracks). The effects rack +section describes this. (See effects rack 2.6.1). + +

+ +

+
+The audio effects rack +

+All audio track types (Input, Output, Group, Wave, Synth, and Aux) have +an effects rack into which audio plugins can be inserted in a chain. +Currently each rack can accomodate up to four plugins. + +

+MusE currently supports LADSPA plugins and DSSI synth and effects +plugins. + +

+Plugins can be added by double-clicking on an entry in the effect rack +in the track info pane (which is shown at the left side of the arranger +when the according track is selected). Right-clicking the rack items +offers a self-explanatory popup menu. + +

+All plugin controls can be automated. (See audio automation +2.7.1). + +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+Learn more about this in the appendix Understanding the Effects Rack: +3 + +

+ +

+ +
+Audio plugin Graphical User Interfaces (GUIs) +

Once a plugin is added, you need a way to +manipulate its controls, which affect its behaviour and operate +on the sound. + +

+MusE can show a generic GUI which contains all of the +plugin's controls arranged in a rather plain generic fashion. + +

+Some plugins may also have a native GUI which looks much better (it +was specifically designed for the plugin). + +

+Both GUI types are opened from the effects rack right-click popup menu. + +

+ +

+
+Automation +

+Automation is the ability to record (or construct) and playback +exact sequences of control movements. + +

+MIDI and audio automation are each currently uniquely different, +but share some similarities. + +

+ +

+
+Audio automation +

+Almost all graphical audio controls in MusE can be automated. + +

+This includes an audio track's volume and pan, and the controls +of any plugins in the effects rack, and if the track is a +synthesizer track, all of the synth's controls. + +

+Each control has a manual adjustment value. This value is shown +when there is no automation data at all, or automation has been +disabled. + +

+For plugin and synth controls, it is usually more desirable to +manipulate automation with the generic plugin GUIs, because +MusE has full control over their behaviour. (See plugin GUIs +2.6.1). + +

+There are a few ways to enter audio automation data: + +

+

+Audio automation modes +

+Each audio track strip has an automation mode button +at the bottom. There are four automation modes: +
+
OFF:
+
Disables all automation, uses manual value always. +
+
READ:
+
Automation data is applied to controls. If any +automation data exists, the manual value is overridden and has +no effect. +
+
TOUCH:
+
Allows you to alter a control at any time, while +transport is stopped or rolling, If rolling, when the control is +released it returns to reading from automation data. +
+
WRITE:
+
Allows to adjust an initial value before rolling +the transport. While rolling, when the control is released it does +not return to reading from automation data. +
+
+Here is a screenshot of automation WRITE mode, and some automation +data, with the track pane automation popup menu showing (see track +automation 2.3.1): + +
+ + + +
Figure 2.11: +Audio automation graphs
+
+ +
Image main_window_with_automation
+
+ +

+ +

+Midi automation +

+MIDI automation is a slightly different concept: Unlike audio +automation, currently there is no automation 'mode' and it doesn't +record graphical control movements. Data is viewed from within +the pianoroll and drum editors, by clicking on the 'Ctrl' button +on those canvases. + +

+Similar to audio controls, each midi control has a manual adjustment +value. This value is overridden when there is midi automation data. + +

+There are a few ways to enter MIDI automation data: + +

+Here is a screen shot of a midi track, containing a midi part +which has been opened with the pianoroll editor and automation +data showing. + +

+The 'Ctrl' popup menu (bottom left) shows available midi controllers +and the green dot indicates there is some data. + +

+ +

+ + + +
Figure 2.12: +MIDI automation graphs
+
+ +
Image main_window_with_midi_automation
+
+ +

+ +

+Configuration +

+ +

+ +

+MIDI ports +

+MIDI ports provide an abstraction layer for your MIDI hardware and +synthesizers (which can be both software and hardware synthesizers), +and other MIDI applications. Port are numbered. In order to produce +sound, each MIDI track is assigned to exactly one MIDI port, to which +the MIDI events are then sent. + +

+The advantage of this abstraction layer is that if your system changes, +for example you change MIDI hardware, then you need only modify the +ports instead of all the tracks using those ports. This is similar +to the audio input and output track abstraction to the outside world. + +

+ +

+MIDI port configuration +

+In the midi/softsynth configuration menu, you must map the port numbers +to the actual devices (by selecting ALSA or jack midi ports, or synth +plugins). + +

+Try left-clicking on the "Ports" column of some MIDI track. +If you use a soft synth, right-clicking the Ports column of the synth +or any track using the synth lets you launch the synth's GUI. + +

+ +

+ + + +
Figure 2.13: +Midi configuration window
+
+ +
Image midi_config_window
+
+ +

+ +

+Columns in the MIDI configuration ports list: +

+
+
GUI:
+
For synthesizer devices, indicates if a gui is available +and if it is showing. Click to show. +
+
I:
+
If present, the port can accept MIDI input. Click to +enable or disable it. +
+
O:
+
If present, the port can send MIDI output. Click to enable +or disable it. +
+
Instrument:
+
Selects the instrument to be used when MIDI is +played through the port. +
+
Device name:
+
Selects or creates a MIDI device assigned to the +port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is +enabled), or soft synthesizers. Jack MIDI devices are created by selecting +Create Jack Device from the Device name drop-down menu. Jack MIDI devices +can be renamed as you wish by clicking the device name. Soft synthesizers +are created by clicking in the soft synthesizer list and then Add +Instance. Or you can simply create a new synthesizer track from the +arranger track list, or even the mixer menus. +
+
In and Out routes:
+
These are for Jack MIDI devices, they are +the routes to and from available Jack MIDI ports. Jack may provide +different alias names for these ports, you can select which alias +is shown. +
+
Default in channels:
+
Auto-connect these port channels to +new midi or drum tracks. +
+
Default out channel:
+
Auto-connect new midi or drum tracks +to this channel on the port. +
+
State:
+
Indicates the state of the port including any errors +opening it. +
+
+ +

+ +

+Global settings +

+ +

+Audio settings +

+ +

+Minimum control period +

+Plugins can usually process an arbitrarily small (or large) amount +of samples. If some plugin control value changes continously, to provide +ideal listening experience, MusE would need to call the plugin 44100 +times a second, asking for one single value at a time. With the minimum +control period setting, the user can force MusE to ask the plugin for +at least N values. Setting this value to 64 would in this situation +make MusE call the plugin +$689=\frac{44100}{64})$ times a second, +asking for 64 values at a time. While doing this will reduce accuracy +of control changes, it may also reduce CPU usage, because calling +the plugin more often, requesting smaller chunks, is more expensive +than calling it seldomly, requesting larger chunks. + +
+Recommendation +
+If you have no performance problems, or if you want to do the final +downmix of your project, set this to a low value. If you're experiencing +performance problems, increasing this value might help. + +

+ +

+ +
+Appendix +

+

+Understanding the effects rack +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+MusE will try to internally create as many independent copies +(instances) of a plugin as necessary, to satisfy the number of channels +in the audio track. +Basically it divides the number of track channels by the number of +plugin audio inputs or outputs to determine how many copies to make. +First it examines the number of plugin audio outputs, and if there are +none, it will examine the number of audio inputs, and if there are +none, it will simply use just one plugin copy. + +

+For mono tracks with plugins having more than one audio input or +output, MusE uses the first input or output and ignores the rest. + +

+For stereo tracks: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
plugin inputsoutputscopiestrack in route channelstrack out route channels
00100
01202
0>=2102
10220
11222
1>=211 (L only)2
>=20120
>=21222
>=2>=2122
+ +

+Notice that on a stereo track with a plugin having one audio input and +two audio outputs, only the first track input route channel is used +(left only). + +

+These same rules apply to inter-plugin audio when more than one plugin +is in the rack chain. Extra audio outputs of one plugin may be ignored +by the next plugin if not used. + +

+Currently specialized plugins with many inputs and/or outputs are not +really useful in MusE. + +

+Nor are so-called 'realtime' control plugins which use audio inputs +and outputs for control signals. + +

+Loud noise alert! Beware of using such plugins in an audio effects +rack. + +

+Example: Consider a stereo Audio Input track with these effect rack + LADSPA plugins: + +

+ +

+ +

+The Comb Splitter has one audio input and two audio outputs. +The Stereo Echo has two audio inputs and two audio outputs. + +

+The stereo Audio Input track will therefore ignore its second +input route connection. It will process the left input only, +separating it into stereo with the Comb Splitter, passing the +split stereo signal into the Stereo Echo, finally producing +stereo output available at the Audio Input track's output routes. + +

+One improvement would be not creating unused redundant plugin copies +between plugins in stereo tracks. +For example, for a plugin having one audio input and one audio output, +feeding a plugin having one audio input and two audio outputs, +the extra copy of the first plugin is redundant and not required, +but currently it is created anyway. +


+ + + diff --git a/muse2/doc/html/single/documentation/img1.png b/muse2/doc/html/single/documentation/img1.png new file mode 100644 index 00000000..36e71d7e Binary files /dev/null and b/muse2/doc/html/single/documentation/img1.png differ diff --git a/muse2/doc/html/single/documentation/index.html b/muse2/doc/html/single/documentation/index.html new file mode 100644 index 00000000..b24ff0be --- /dev/null +++ b/muse2/doc/html/single/documentation/index.html @@ -0,0 +1,1702 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + +
+ +

+
+ +
Image muse2 + +
+
+ +

+Contents +

+ + + + +

+What is this? +

+You are, if you have printed this document, holding in your hand the +written documentation for the audio and midi sequencer MusE version 2. +
http://www.muse-sequencer.org is MusE's home on the internet where +everything MusE releated should be possible to find, software, this +documentation, forums, mailing lists, bug reporting, FAQs. If you have +this document but not the software head on over there to find what it's +all about. + +

+User's manual +

+ +

+ +

+Introduction +

+ +

+A brief history of computer audio and MusE +

+To quickly summarize over a decades open source development: in 1999 Werner + Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first +few releases (actually not few, Werner relentlessly churned out new releases) +MusE was only a midi sequencer. The target was to create a fully fledged +midi sequencer for the Linux operating system. Over the years audio was +added among with other things implemented and sometimes abandoned. +Today MusE is a stable and feature rich music creation environment which +strives to encompass most of the music recording process, creation, editing, +mastering. + +

+ +

+Definitions +

+CTRL refers to the control key on the keyboard, e.g. CTRL+C +means to press and hold the control key while pressing the c key. Make sure +you know where you have it so you won't accidentally lose control +(bad jokes are the best jokes, so say we all!). +
SHIFT refers to the shift key on the keyboard, see above for usage +
ALT refers to the alt key on the keyboard, see above for usage +
$> is used as a generic definition for a terminal prompt. When the +manual lists a command that shall be typed, the prompt is not part of the +command. +
+Keys are always referred to in bold uppercase, e.g. A. For instance +SHIFT+A for the key a pressed together with the shift key. +
+Sometimes terminal examples are written tabbed in with a fixed font to +visualize more closely what something looks like on the screen. +E.g. +
$> muse2 +
+

+ +

+Getting up and running for impatient people +

+Install MusE from the repository of your chosen distribution. +To get decent performance start http://jackaudio.org/Jack with +the following command in a terminal: +
$> jackd -d alsa -d hw:0 -p 256 +
+Or, if you prefer, use the launcher utility +http://qjackctl.sourceforge.net/QJackCtl to get some +help starting Jack. +After this, start MusE from the menu or fire up another terminal and +type + +

+muse2. +
+If this didn't work out read on for the slightly more complete route for +getting things started. + +

+ +

+Getting up and running +

+ +

+Installation from binaries +

+There are several ways to install MusE depending on your situation. The +most convenient way is to install a prepackaged version from your chosen +distribution. The drawback of this is that it may not be the most recent +version, though often there is a more recent package from a private packager. + +

+Installation from source +

+Building MusE from source is not hard, there are a number of prerequistes +that must be met but the actual building should be painless (ha, famous +last words). +
+Please follow the README in the source package and/or read the instructions +on the homepage: http://muse-sequencer.org/index.php/Installation +

+ +

+Hardware +

+MusE on the Linux platform supports midi through ALSA and Jack-midi and audio +through Jack. For information on what hardware is supported there are some +convenient places to check: + + +Also, as is often a very good approach for Linux and open source, the +various forums available on the internet often contain good information. +Chances are someone has already tried your configuration and/or had your +specific problem and the solution is already written down. + +

+Launching +

+After installation the binary muse2 is installed on the computer. If MusE +was installed from a distribution repository the binary may have a +different name depending on the distribution policies. Most distributions +do however install a menu entry so MusE should be conveniently available +from there. + +

+Audio preconditions +

+In the standard case MusE expects to find and connect to the Jack audio +server http://jackaudio.org. Make sure jack is installed (if MusE was +installed with a distribution-package Jack will very likely already be +installed) For Jack to run with best performance your system should be +sufficiently tuned to allow it to run with realtime capabilities. The +realtime configuration is configuration of the operating system and roughly +consists of two parts. + +
    +
  1. By default on most distros only the superuser lets applications setup +realtime capabilities. Please see the APPENDIX for setting up realtime +
  2. +
  3. Maximizing performance. A standard linux installation may not able +to reach the performance required by a power user. This requires exchanging +the linux kernel for a so called lowlatency kernel, this is also covered by +the realtime APPENDIX. +
  4. +
+ +

+ +

+Running MusE +

+Find MusE in the menu or open a terminal and enter muse2. + +

+$> muse2 +
+A splash screen should pop up followed +by the main application window and you are off! +
+If an error like the screenshot below pops up the Jack audio server is +either not running or started as a different user than what you are trying +to start MusE as. + +

+ + + +
Figure 2.1: +Jack server missing
+
+ +
Image no_audio
+
+ +

+Midi only +

+MusE can be started in Midi-only mode where MusE does not have any external +dependencies apart from ALSA midi. In this case start MusE from a terminal: +$> muse2 -a + +

+ +

+ALSA midi with Jack +

+If Jack is running, by default MusE will not use ALSA devices, preferring +Jack midi instead. To force ALSA devices to be used as well as Jack +midi, start MusE with the -A option: $> muse2 -A + +

+ +

+Beginners tutorial +

+To get a quick grip of what MusE can achieve please follow this beginners +tutorial. + +

+Midi Setup +

+First off, fire up MusE as was described in the previous chapter, making +sure that the jack audio server is started with sufficient configuration +to allow for audio output without breakup. Also make sure your system can +make sound. + +

+Soft synth test +

+With MusE up and running right click in the Track-pane (see +Fig. 2.8) and select +Add Synth > MESS > vam soft synth. +A Soft Synth track called vam-0 should appear as well as a separate GUI +for the synthesizer. + +

+Now right click once more in the Track-pane and select Add Midi +Track. Another track appears called Track 1, and its track list Port +column should show it is bound to the synth that was just created vam-0. +If it is not, click on the Track 1 Port column to open a drop-down list +of available devices and choose vam-0. + +

+ +

+r0.05 +Image arrow_tool + +
+Now select the drawing tool icon +from the toolbar, alternatively press the shortcut key D. +Move the mouse over to the arranger canvas as referenced in +Fig. 2.8 +and point at the midi track, the mouse should have changed to a small pencil. +Draw a Part along the midi track using the mouse. For this exercise it is +not important where or how large the drawn Part is. When you are done double +click on the drawn part. This will open up the Piano Roll editor. To the +left of the Piano Roll there are piano keys in a vertical line, try clicking +on the keys in this virtual keyboard each click should be rewarded with a +synth sound (maybe of questionable quality, a sound nevertheless) + +
+ + + +
Figure 2.2: +vam synthesizer
+
+ +
Image vam_synth
+
+ +

+ +

+Missing sound +

+If you got sound from the previous exercise you can carry on to the next, +or keep reading for further enlightenment in case you come upon trouble +later on. If there is no sound we need to do some fault hunting. First +off, click on Arranger window once more and select the vam-0 track in the +track-pane. + +
+ + + +
Figure 2.3: +Midi editor view
+
+ +
Image main_window_with_midi_editor_vam
+
+Now bring back Piano Roll window and align the windows so you +can see the piano keys as well as the Meter on the Mixer Strip (see the +5 Function by function chapter for more information on these windows). +The result should be something like the following: + +

+When pressing one of the keys on virtual Keyboard the Meter on the Mixer +Strip should light up in green to visualize that the Synth is making +sound, if it is not try to trace back your steps and and see if you did +anything differently than described. +Now, if the Meter lights up but there is still no sound we need to +check the routing between the tracks. Click on the Arranger window again +and select the Out 1 track, this is the predefined output which MusE by +default loads at startup, at the bottom of Mixer Strip there are two +buttons looking like tele- jacks, these bring up the inputs and outputs +of the track, click on the right one, the output and make sure that it is +connected to some valid outputs on your system. + +

+r0.25 +Image output_routing + +
+Click on the outputs to select them, if you did changes here go back and +try clicking on the Piano Roll keyboard again, hopefully it helped. If there +still are problems make sure your system actually can make sound through +Jack, this is however getting outside the scope of this manual. +
+
This might be the time to bring up the concept of community support. +Open source software could never be what it is without the support given by +individuals on forums and mailinglists, if the information given in this +document is not enough, try googling your problem and/or get in touch with +one of the online forums for MusE or Linux audio in general. See some pointers +in the Support chapter. + +

+ +

+Recording Midi +

TBD + +

+Recording Audio +

+At this point we'll make a a slight detour into full on audio recording. Getting +audio out of MusE has already been covered in the previous chapters so we will +concentrate on the additional steps needed to record onto an audio track. +
+
+When MusE is first fired up, the +output track has already been created (more about this in the chapter about +templates), to proceed with audio recording we need to add two additional tracks, a +wave track and an input track. +
+When MusE is first started right click in an empty space on the track view + +
+ + + +
Figure 2.4: +Add track
+
+ +
Image main_window_add_track
+
+and select Add Audio Input. Right click again and also select +Add Wave Track. Two additional tracks are now visible in the Arranger, +"Input 1" and "Track 1", bring up the mixer with F10 and you should see +the following configuration. + +
+ + + +
Figure 2.5: +Mixer with one input
+
+ +
Image mixer_with_one_input
+
+ +
+Note the buttons on each mixer strip. hover over them to see their +functionality. For more information on all the buttons see coming chapters +about the mixer. For now lets just do what we must. +
+1. click on the stereo symbol over the slider to change the input to a mono track. +
+2. do the same for the wave track (optional) +
+3. click on the Mute (gray speaker) icon on the input track to unmute it. +
+4. click on the input routing button (see the tooltip, it looks like a tele plug) +on the input track and select an appropriate connection from your system. +
+5. click on the output routing button on the input track and select +Track 1 +
+
+Already after the meter on the input track should be able to display that there +is incoming sound from your sound source. If there actually is sound coming +from your sound source, that is. +
+We are now nearly ready to start recording. First we need to select a location +to store the files. MusE does not use a centralized storage of soundfiles but +uses the path of the song-file (extension .med) as guidance as to where the +audio files should be placed. Now as it happens MusE will prohibit us from +starting a recording until the songfile has been stored. So lets take advantage +of this behaviour and just go ahead and try to record. Let's get started. +
+In the mixer click on the red record dot on the Audio Track to arm it +for recording (or enable if you will). Now when there is audio coming into the +input it will also show up on the Audio Track. Also note that all the input and +output routing buttons on the tracks now have the same gray color, this means +that all of the tracks have a proper connection. + +
+ + + +
Figure 2.6: +Mixer buttons
+
+ +
Image mixer_with_one_input_buttons
+
+ +
+All fine and dandy. Now bring up the arranger window and find the round, red on +white record button and click on it. This is your queue to MusE to +prepare for recording. However since we have not saved our song we are presented +with a dialog to do just that. +
+
+ + + +
Figure 2.7: +Save song
+
+ +
Image project_my_first_song
+
+Note the check box for creating a project folder, when working with audio this +is very much recommended or you may soon loose track of what audio files belong +to which song. +
+Finally we are ready to start recording! The process is completed by clicking +on the Play button in the Arranger. If all went well MusE then starts +to record a wave file from the Input Track placed in your song directory. +
+When you wish to stop recording press Stop in the Arranger, now the +resulting waveform should be visible in the Arranger. After rewinding the Play +position and pressing Play again the resulting sound should be audible +through the connected output. + +

+ +

+Basic overview +

+In this section we will make a step by step walk-through of all the +different editors, their purpose and what functions they support. + +

+ +

+Main/Arranger +

+ +

+ + +

+ + + +
Figure 2.8: +MusE main window
+
+ +
Image main_window_annotated
+
+Above is the main window of MusE, the Arranger, this is what greets you +when launching MusE. The Arranger consists of two main parts, the Track-pane +and the Arranger canvas. The Track-pane lists all currently visible tracks +and the Arranger canvas contains all Parts of the composition. The +screenshot above shows an empty project. Below is MusE with a song in +progress, turns out it wasn't a very good song, but for our purposes it +is fine. In the below screenshot there are a lot of tracks visible in the +Track-pane, each have an icon which indicate it's type, wave-track, input, +output etcetera, more about that later. In the Arranger canvas a number of +parts are visible, the ones in yellow are in this composition wave files, +the multicolored line are different Parts of a drum track. + +

+ +

+ + + +
Figure 2.9: +MusE main window with arrangement
+
+ +
Image main_window_with_arrangement
+
+ +

+ +

+
+Mixer +

+Choosing View > Mixer A or B from the menu in the main +window will bring up the mixer as viewed below. The mixer will open with +all options enabled, showing channel strips for all tracks in the current +setup, depending on how far you have gotten this view may become very large, +at which point it may be a good idea to limit what is viewed in the Mixer. +From the view menu all the different kinds of tracks can be toggled on/off +from the mixer. Some may find it a good idea to use the two mixers A and B +setup with different setup and store this in your song template(s), more +about this in the Song Template section. It can be argued that everything +in MusE is a track analogous to the Unix idiom that everything is a file. +The types of tracks visible in the mixer (and track-pane) are: + +
+r0.5 +Image mixer + +
+ + + +

+There is also a Midi Track variation called Drum Track, they are +however not distinguishable from Midi Tracks in the Mixer. Also the +strips for midi tracks are different in the Mixer than in the +Track-pane view. + +

+ +

+Tracks and parts +

+MusE arranges your music in tracks and parts. The following +section shall provide you an overview of how things are done with MusE. +If you are or were a Cubase or Cakewalk user, you will feel familiar with +this. + +

+ +

+Tracks +

+There are two general classes of tracks: MIDI tracks and audio +tracks. MIDI tracks (and drum tracks which are internally MIDI tracks) +can hold note data. The Wave track is a type of audio track which holds +wave data. There are also several other kinds of audio tracks. + +

+ +

+MIDI tracks +

+MIDI and drum tracks hold MIDI event data. They don't differ much, +except that drum tracks offer a special editor which is more suitable +for drum editing. + +

+ +

+Wave tracks +

+They hold audio data which can be just played back or be piped through +effect plugin chains. They offer automation for these plugins. + +

+ +

+Audio input tracks +

+These provide the path for your audio data from outside into your +project. Set up the physical audio inputs you want to connect your +audio input track with, and then route the input tracks to various +other tracks such as wave tracks. + +

+ +

+Audio output tracks +

+These provide the path for your project's audio data to outside. Set +up the physical audio outputs you want to connect your audio out track +with, and then route various other tracks, such as wave tracks, to +the output tracks. + +

+ +

+Audio group tracks +

+Group tracks are like busses, where you can route other tracks to +them, then route the groups to other tracks. Since group tracks have +all the features of other audio tracks, like volume and pan, they +provide a convenient common routing point where you have control of +the sound before it is passed to other tracks. + +

+ +

+
+Audio aux tracks +

+These provide a more convenient way to mix several audio tracks +together. With each audio aux track added, other audio tracks will +gain a common send knob for adjusting the level sent to the aux +track. This can be more convenient than using several group tracks. + +

+ +

+Synthesizer tracks +

+This type of track is a software synthesizer which MIDI and drum tracks +can be assigned to. + +

+ +

+Creation +

+You can create a track by either right-clicking in the arranger's track list and then adding the desired track, or via the edit menu. + +

+ +

+Attributes +

+Tracks have several attributes: +
+
Mute:
+
If you click on the Mute field (denoted with +a "M" column header), the track gets muted and stops producing sound. +
+
Solo:
+
The solo button ("S" column +header) singles out a track for listening. It mutes +some other tracks but may phantom solo others. +For more info see the section on soloing: 2.5 and +phantom soloing: 2.5.1 +
+
Record:
+
The R column "arms" your track for recording. +When you rec-arm your song and have no tracks rec-armed, you won't be +able to record anything. See also the config option "move rec-arm with selection". +
+
Track name:
+
Double-click to edit the track name. +
+
Port:
+
For MIDI tracks, this lets you select the MIDI +port to which the events should be routed. This can be your physical +synthesizer or a software synthesizer. For soft synths, this is the +port the synth is associated to. For other track types, this is disabled. +
+
Channel:
+
For MIDI tracks, this is the MIDI channel the +output is sent to. For any kind of audio tracks, this is the number of +channels (mono, stereo). +
+
Automation:
+
For audio tracks, +this lets you set up the automation display in the arranger. +(See automation 2.7.1). Clicking this will provide you +with a popup menu with lots of submenus. Clicking on a submenu will +select or unselect it showing or hiding the automation parameter as a +graph overlaid on top of the track. +
+The submenus let you select the color you want to associate with the +automation parameter. There you can also assign midi controllers to +the parameters, a dialog is shown where you can manually choose the +midi controller, with a learn button to 'listen for' and +automatically recognize any midi controller operated by you. + +

+

+
Clef:
+
For MIDI tracks, you can specify a clef here. This +only affects the score editor. + +

+

+
+ +

+ +

+The trackinfo side bar +

+In the arranger and the part editors, you'll have a trackinfo sidebar +on the left side. You can set up track-type specific things there. + +

+ +

+
+MIDI trackinfo sidebar +

+The MIDI trackinfo sidebar lets you change program, volume, pan and +more. This sidebar can also be viewed at the left of the pianoroll +editor. + +
+Old style drum tracks: +
+These are MIDI tracks as well, but with a few differences. They allow +you to map certain drum sounds with different input notes, and you +can change the output settings of a certain "drum instrument" without +having to alter each single event. + +

+However, they have certain limitations: They only can handle 128 sounds +(even if you have more synthes), they aren't really compatible with +MIDI tracks (you can interchange parts between them, but if you touched +the drum list, you'll get unexpected results), you can't set a program +for the used channel and more. + +

+ +

+New style drum tracks +

+Because of these limitations, we introduced the new-style drum tracks. +They're not fully compatible with the old drum tracks, so the old are +still retained. Under "Global Settings", "GUI settings", you can set +up whether you prefer the old or new. + +

+They are handled exactly like plain MIDI tracks (staying compatible with +them), and offer all of the functionality, though in a different way. +They allow you to re-order the drum map efficiently, you can open parts +from multiple drum tracks in one drum editor (MusE will separate +the sounds from different tracks according to your settings, see the +"Window Config" menu), and you can set programs as with normal MIDI tracks. + +

+ +

+MIDI trackinfo controls: +
+
+
Output port:
+
This drop-down list selects the midi port +to send midi output from this track. +
+
Output channel:
+
This box selects the midi channel to be +used on the output port. +
+
Input and output routing:
+
Selects midi ports and +channels to receive midi from, and soloing paths. (See Routes +2.4). +
+
Midi through:
+
This button selects whether midi input is +passed through to the selected output port. +
+Depending on your midi devices and settings, there are cases when +this should be off such as using the same port and channel for +input and output (otherwise a double-note echo will be heard), +and cases when it must be on such as when using a synthesizer track +as output device. +
+
Input detect indicator:
+
Blinks when midi activity is +detected on the selected midi channels on the selected midi input +ports. +
+
Transpose:
+
This transposes midi input notes up or down +in pitch. This is very useful if your midi keyboard hasn't enough +keys or the selected output device plays an octave too low or high, +and you would like to shift the octave of the incoming notes to +compensate. +
+
Delay:
+
Adjusts the delay of the notes. +
+
Length:
+
Adjusts the length of the notes. +
+
Velocity:
+
Adjusts the velocity of incoming notes. +Use it to compensate for a too-loud or too-soft keyboard. +
+
Compression:
+
Adjusts the compression of incoming note +velocities. Use it to make soft incoming notes louder, and loud +notes not so loud. +
+
Instrument:
+
Selects the midi instrument patch to be used +by the selected output port. This is equivalent of dialing the patch +in the bank and program boxes, except it displays a more friendly +patch name as defined by the selected output port's midi +instrument. See instruments, or port configuration +2.8.1 +
+
H-Bank:
+
Selects the high bank number of the current patch. +
+
L-Bank:
+
Selects the low bank number of the current patch. +
+
Prog:
+
Selects the program number of the current patch. +
+
Volume:
+
Adjusts the midi volume controller. +
+
Pan:
+
Adjusts the midi pan controller. +
+
+The buttons beside the Prog, Volume, and Pan boxes store the value, +at the current transport position, for midi automation. (See +automation 2.7.1). + +

+Note that the 'Prog' button stores H-Bank and L-Bank along with +'Prog' value, so there are no H-Bank and L-Bank buttons. + +

+The 'All' button simply stores all three Program (and banks), Volume, +and Pan values at once. + +

+Tip: If the Song Type is GM, GS, or XG, you may need to store +desired values at transport position zero, otherwise your adjustments +may be overriden by the instrument when the transport is moved back +to position zero. If this behaviour is undesired, you can set the +Song Type to 'NO' meaning no song type. + +

+ +

+Audio trackinfo sidebar +

+Unlike the midi trackinfo sidebar, the audio trackinfo side bar +is nothing more than an embedded audio mixer strip, the exact same +strip as found in the mixers. (See mixer 2.2.2). + +
+Effects rack: +
+On the top of the audio trackinfo sidebar, there is an effects rack +which allows you to apply various plugins on the audio. For more +information on this, refer to 2.6.1. + +

+ +

+Parts +

+Within MIDI, drum and wave tracks, you can create parts. Parts +are chunks of coherent notes or wave data which can be moved around, +copied, cloned and deleted independent from other parts. + +

+Parts are created by selecting the pencil tool and then drawing onto +the right part area in the arranger. You can move them with the arrow +tool, delete them using the DEL key, and a right-click opens +a popup menu. This menu allows you even more stuff, such as setting +the part's color, saving the part to disk etc.. You can use +CTRL+C and CTRL+V for copying and pasting parts. +CTRL+B pastes the part as a clone. Pressing SHIFT +additionally provides you a dialog which allows you to paste the part +multiple times and set more stuff. + +

+You can also copy parts with the mouse by moving the part with the mouse +while holding down the CTRL key. + +

+ +

+
+Routes +

+Routes are how tracks are connected together and to the outside world. +(They are also how Jack midi ports connect to the outside world. See +midi port configuration 2.8.1). +Each track strip has two buttons whose icons look like plugs. One button +is for input routing and the other is for output routing. Clicking on +these buttons will pop up a menu of available input or output routes that +you can connect to. Most audio tracks list other tracks to connect to, +but audio input and output tracks are special: Audio input track input +routing menus list available Jack audio input ports. Conversely audio +output track output routing menus list available Jack audio output ports. + +

+ +

+r0.25 +Image output_routing + +
+ +

+Meanwhile MIDI and drum tracks allow you to route available MIDI ports +and channels to the track using a handy popup matrix. + +

+ +

+r0.25 +Image midi_routing_matrix + +
+ +

+ +

+
+Anti circular routing +

+Any routing menu item which would cause a circular routing condition +is grayed out. Find out why the condition would exist by examining +routing paths involved and correct the situation if required. + +

+Also, you cannot use a track's aux sends if the track has an input +route path from ANY Aux Track. (See aux tracks 2.3.1). +Aux send knobs and labels are disabled in that case. + +

+ +

+
+Soloing chain routes +

+Soloing chains (see solo chains 2.5.2) are really just +routes like any other. The available solo chaining paths are displayed +in the routing popup menus. + +

+ +

+
+Track soloing +

+Soloing allows you to single out a track for listening while muting others, +without you having to mute the other tracks. (See soloing track attribute +2.3.1). + +

+ +

+
+Phantom soloing +

+In order to solo a track and mute others so that it is heard, MusE +employs 'phantom' soloing: When a track is soloed, MusE automatically +solos all tracks routed to and from this track. (See routes +2.4). A phantom soloed track is indicated by a black square +in the track pane solo column. (See track attributes +2.3.1). + +

+ +

+ + + +
Figure 2.10: +Soloing, with phantom soloing
+
+ +
Image soloing_window
+
+ +

+ +

+
+Soloing chains +

+When an audio output track sends audio to some external entity, such +as an external running application, and audio from the external entity +is fed back into a MusE audio input track, solo chains allow you to +solo the input or output, and MusE will complete the path automatically +soloing the other, and all paths that came before or after it. + +

+Solo chains also work with MIDI tracks chained to audio inputs: +When a MIDI track drives some MIDI device whose audio is fed into MusE, +solo chains allow the entire chain to be soloed. + +

+Solo chains are accessed via routing menus. (See solo chain routes +2.4.2). + +

+ +

+
+Plugins +

+Plugins are small add-ons which can process a track's data. + +

+MIDI plugins operate on midi and drum tracks, and are found in +the Midi menu. + +

+Audio plugins can be applied to any track handling audio (that is, +inputs, outputs, wave tracks, synth tracks). The effects rack +section describes this. (See effects rack 2.6.1). + +

+ +

+
+The audio effects rack +

+All audio track types (Input, Output, Group, Wave, Synth, and Aux) have +an effects rack into which audio plugins can be inserted in a chain. +Currently each rack can accomodate up to four plugins. + +

+MusE currently supports LADSPA plugins and DSSI synth and effects +plugins. + +

+Plugins can be added by double-clicking on an entry in the effect rack +in the track info pane (which is shown at the left side of the arranger +when the according track is selected). Right-clicking the rack items +offers a self-explanatory popup menu. + +

+All plugin controls can be automated. (See audio automation +2.7.1). + +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+Learn more about this in the appendix Understanding the Effects Rack: +3 + +

+ +

+ +
+Audio plugin Graphical User Interfaces (GUIs) +

Once a plugin is added, you need a way to +manipulate its controls, which affect its behaviour and operate +on the sound. + +

+MusE can show a generic GUI which contains all of the +plugin's controls arranged in a rather plain generic fashion. + +

+Some plugins may also have a native GUI which looks much better (it +was specifically designed for the plugin). + +

+Both GUI types are opened from the effects rack right-click popup menu. + +

+ +

+
+Automation +

+Automation is the ability to record (or construct) and playback +exact sequences of control movements. + +

+MIDI and audio automation are each currently uniquely different, +but share some similarities. + +

+ +

+
+Audio automation +

+Almost all graphical audio controls in MusE can be automated. + +

+This includes an audio track's volume and pan, and the controls +of any plugins in the effects rack, and if the track is a +synthesizer track, all of the synth's controls. + +

+Each control has a manual adjustment value. This value is shown +when there is no automation data at all, or automation has been +disabled. + +

+For plugin and synth controls, it is usually more desirable to +manipulate automation with the generic plugin GUIs, because +MusE has full control over their behaviour. (See plugin GUIs +2.6.1). + +

+There are a few ways to enter audio automation data: + +

+

+Audio automation modes +

+Each audio track strip has an automation mode button +at the bottom. There are four automation modes: +
+
OFF:
+
Disables all automation, uses manual value always. +
+
READ:
+
Automation data is applied to controls. If any +automation data exists, the manual value is overridden and has +no effect. +
+
TOUCH:
+
Allows you to alter a control at any time, while +transport is stopped or rolling, If rolling, when the control is +released it returns to reading from automation data. +
+
WRITE:
+
Allows to adjust an initial value before rolling +the transport. While rolling, when the control is released it does +not return to reading from automation data. +
+
+Here is a screenshot of automation WRITE mode, and some automation +data, with the track pane automation popup menu showing (see track +automation 2.3.1): + +
+ + + +
Figure 2.11: +Audio automation graphs
+
+ +
Image main_window_with_automation
+
+ +

+ +

+Midi automation +

+MIDI automation is a slightly different concept: Unlike audio +automation, currently there is no automation 'mode' and it doesn't +record graphical control movements. Data is viewed from within +the pianoroll and drum editors, by clicking on the 'Ctrl' button +on those canvases. + +

+Similar to audio controls, each midi control has a manual adjustment +value. This value is overridden when there is midi automation data. + +

+There are a few ways to enter MIDI automation data: + +

+Here is a screen shot of a midi track, containing a midi part +which has been opened with the pianoroll editor and automation +data showing. + +

+The 'Ctrl' popup menu (bottom left) shows available midi controllers +and the green dot indicates there is some data. + +

+ +

+ + + +
Figure 2.12: +MIDI automation graphs
+
+ +
Image main_window_with_midi_automation
+
+ +

+ +

+Configuration +

+ +

+ +

+MIDI ports +

+MIDI ports provide an abstraction layer for your MIDI hardware and +synthesizers (which can be both software and hardware synthesizers), +and other MIDI applications. Port are numbered. In order to produce +sound, each MIDI track is assigned to exactly one MIDI port, to which +the MIDI events are then sent. + +

+The advantage of this abstraction layer is that if your system changes, +for example you change MIDI hardware, then you need only modify the +ports instead of all the tracks using those ports. This is similar +to the audio input and output track abstraction to the outside world. + +

+ +

+MIDI port configuration +

+In the midi/softsynth configuration menu, you must map the port numbers +to the actual devices (by selecting ALSA or jack midi ports, or synth +plugins). + +

+Try left-clicking on the "Ports" column of some MIDI track. +If you use a soft synth, right-clicking the Ports column of the synth +or any track using the synth lets you launch the synth's GUI. + +

+ +

+ + + +
Figure 2.13: +Midi configuration window
+
+ +
Image midi_config_window
+
+ +

+ +

+Columns in the MIDI configuration ports list: +

+
+
GUI:
+
For synthesizer devices, indicates if a gui is available +and if it is showing. Click to show. +
+
I:
+
If present, the port can accept MIDI input. Click to +enable or disable it. +
+
O:
+
If present, the port can send MIDI output. Click to enable +or disable it. +
+
Instrument:
+
Selects the instrument to be used when MIDI is +played through the port. +
+
Device name:
+
Selects or creates a MIDI device assigned to the +port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is +enabled), or soft synthesizers. Jack MIDI devices are created by selecting +Create Jack Device from the Device name drop-down menu. Jack MIDI devices +can be renamed as you wish by clicking the device name. Soft synthesizers +are created by clicking in the soft synthesizer list and then Add +Instance. Or you can simply create a new synthesizer track from the +arranger track list, or even the mixer menus. +
+
In and Out routes:
+
These are for Jack MIDI devices, they are +the routes to and from available Jack MIDI ports. Jack may provide +different alias names for these ports, you can select which alias +is shown. +
+
Default in channels:
+
Auto-connect these port channels to +new midi or drum tracks. +
+
Default out channel:
+
Auto-connect new midi or drum tracks +to this channel on the port. +
+
State:
+
Indicates the state of the port including any errors +opening it. +
+
+ +

+ +

+Global settings +

+ +

+Audio settings +

+ +

+Minimum control period +

+Plugins can usually process an arbitrarily small (or large) amount +of samples. If some plugin control value changes continously, to provide +ideal listening experience, MusE would need to call the plugin 44100 +times a second, asking for one single value at a time. With the minimum +control period setting, the user can force MusE to ask the plugin for +at least N values. Setting this value to 64 would in this situation +make MusE call the plugin +$689=\frac{44100}{64})$ times a second, +asking for 64 values at a time. While doing this will reduce accuracy +of control changes, it may also reduce CPU usage, because calling +the plugin more often, requesting smaller chunks, is more expensive +than calling it seldomly, requesting larger chunks. + +
+Recommendation +
+If you have no performance problems, or if you want to do the final +downmix of your project, set this to a low value. If you're experiencing +performance problems, increasing this value might help. + +

+ +

+ +
+Appendix +

+

+Understanding the effects rack +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+MusE will try to internally create as many independent copies +(instances) of a plugin as necessary, to satisfy the number of channels +in the audio track. +Basically it divides the number of track channels by the number of +plugin audio inputs or outputs to determine how many copies to make. +First it examines the number of plugin audio outputs, and if there are +none, it will examine the number of audio inputs, and if there are +none, it will simply use just one plugin copy. + +

+For mono tracks with plugins having more than one audio input or +output, MusE uses the first input or output and ignores the rest. + +

+For stereo tracks: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
plugin inputsoutputscopiestrack in route channelstrack out route channels
00100
01202
0>=2102
10220
11222
1>=211 (L only)2
>=20120
>=21222
>=2>=2122
+ +

+Notice that on a stereo track with a plugin having one audio input and +two audio outputs, only the first track input route channel is used +(left only). + +

+These same rules apply to inter-plugin audio when more than one plugin +is in the rack chain. Extra audio outputs of one plugin may be ignored +by the next plugin if not used. + +

+Currently specialized plugins with many inputs and/or outputs are not +really useful in MusE. + +

+Nor are so-called 'realtime' control plugins which use audio inputs +and outputs for control signals. + +

+Loud noise alert! Beware of using such plugins in an audio effects +rack. + +

+Example: Consider a stereo Audio Input track with these effect rack + LADSPA plugins: + +

+ +

+ +

+The Comb Splitter has one audio input and two audio outputs. +The Stereo Echo has two audio inputs and two audio outputs. + +

+The stereo Audio Input track will therefore ignore its second +input route connection. It will process the left input only, +separating it into stereo with the Comb Splitter, passing the +split stereo signal into the Stereo Echo, finally producing +stereo output available at the Audio Input track's output routes. + +

+One improvement would be not creating unused redundant plugin copies +between plugins in stereo tracks. +For example, for a plugin having one audio input and one audio output, +feeding a plugin having one audio input and two audio outputs, +the extra copy of the first plugin is redundant and not required, +but currently it is created anyway. +


+ + + diff --git a/muse2/doc/html/single/documentation/main_window_add_track.png b/muse2/doc/html/single/documentation/main_window_add_track.png new file mode 100644 index 00000000..7750ca7f Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_add_track.png differ diff --git a/muse2/doc/html/single/documentation/main_window_annotated.png b/muse2/doc/html/single/documentation/main_window_annotated.png new file mode 100644 index 00000000..f8f7701f Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_annotated.png differ diff --git a/muse2/doc/html/single/documentation/main_window_with_arrangement.png b/muse2/doc/html/single/documentation/main_window_with_arrangement.png new file mode 100644 index 00000000..8d391d9f Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_with_arrangement.png differ diff --git a/muse2/doc/html/single/documentation/main_window_with_automation.png b/muse2/doc/html/single/documentation/main_window_with_automation.png new file mode 100644 index 00000000..3930c0da Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_with_automation.png differ diff --git a/muse2/doc/html/single/documentation/main_window_with_midi_automation.png b/muse2/doc/html/single/documentation/main_window_with_midi_automation.png new file mode 100644 index 00000000..5357a6d3 Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_with_midi_automation.png differ diff --git a/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png b/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png new file mode 100644 index 00000000..bedf6250 Binary files /dev/null and b/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png differ diff --git a/muse2/doc/html/single/documentation/midi_config_window.png b/muse2/doc/html/single/documentation/midi_config_window.png new file mode 100644 index 00000000..f979ad34 Binary files /dev/null and b/muse2/doc/html/single/documentation/midi_config_window.png differ diff --git a/muse2/doc/html/single/documentation/midi_routing_matrix.png b/muse2/doc/html/single/documentation/midi_routing_matrix.png new file mode 100644 index 00000000..ac080a92 Binary files /dev/null and b/muse2/doc/html/single/documentation/midi_routing_matrix.png differ diff --git a/muse2/doc/html/single/documentation/mixer.png b/muse2/doc/html/single/documentation/mixer.png new file mode 100644 index 00000000..22d9f2b7 Binary files /dev/null and b/muse2/doc/html/single/documentation/mixer.png differ diff --git a/muse2/doc/html/single/documentation/mixer_with_one_input.png b/muse2/doc/html/single/documentation/mixer_with_one_input.png new file mode 100644 index 00000000..629328d7 Binary files /dev/null and b/muse2/doc/html/single/documentation/mixer_with_one_input.png differ diff --git a/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png b/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png new file mode 100644 index 00000000..c6ad7b0c Binary files /dev/null and b/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png differ diff --git a/muse2/doc/html/single/documentation/muse2.png b/muse2/doc/html/single/documentation/muse2.png new file mode 100644 index 00000000..84a28d8a Binary files /dev/null and b/muse2/doc/html/single/documentation/muse2.png differ diff --git a/muse2/doc/html/single/documentation/no_audio.png b/muse2/doc/html/single/documentation/no_audio.png new file mode 100644 index 00000000..1e62245c Binary files /dev/null and b/muse2/doc/html/single/documentation/no_audio.png differ diff --git a/muse2/doc/html/single/documentation/output_routing.png b/muse2/doc/html/single/documentation/output_routing.png new file mode 100644 index 00000000..08af67fa Binary files /dev/null and b/muse2/doc/html/single/documentation/output_routing.png differ diff --git a/muse2/doc/html/single/documentation/project_my_first_song.png b/muse2/doc/html/single/documentation/project_my_first_song.png new file mode 100644 index 00000000..488faad2 Binary files /dev/null and b/muse2/doc/html/single/documentation/project_my_first_song.png differ diff --git a/muse2/doc/html/single/documentation/soloing_window.png b/muse2/doc/html/single/documentation/soloing_window.png new file mode 100644 index 00000000..72b72d63 Binary files /dev/null and b/muse2/doc/html/single/documentation/soloing_window.png differ diff --git a/muse2/doc/html/single/documentation/vam_synth.png b/muse2/doc/html/single/documentation/vam_synth.png new file mode 100644 index 00000000..f2e3bad4 Binary files /dev/null and b/muse2/doc/html/single/documentation/vam_synth.png differ diff --git a/muse2/doc/html/split/developer_docs/developer_docs.css b/muse2/doc/html/split/developer_docs/developer_docs.css new file mode 100644 index 00000000..d3fede21 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/developer_docs.css @@ -0,0 +1,34 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ +DIV.navigation { } +SPAN.textit { font-style: italic } +SPAN.arabic { } +SPAN.textbf { font-weight: bold } diff --git a/muse2/doc/html/split/developer_docs/developer_docs.html b/muse2/doc/html/split/developer_docs/developer_docs.html new file mode 100644 index 00000000..0a0f037c --- /dev/null +++ b/muse2/doc/html/split/developer_docs/developer_docs.html @@ -0,0 +1,113 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + + + + +

+ + + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/img1.png b/muse2/doc/html/split/developer_docs/img1.png new file mode 100644 index 00000000..85b2087d Binary files /dev/null and b/muse2/doc/html/split/developer_docs/img1.png differ diff --git a/muse2/doc/html/split/developer_docs/img2.png b/muse2/doc/html/split/developer_docs/img2.png new file mode 100644 index 00000000..b5a0cc4b Binary files /dev/null and b/muse2/doc/html/split/developer_docs/img2.png differ diff --git a/muse2/doc/html/split/developer_docs/img3.png b/muse2/doc/html/split/developer_docs/img3.png new file mode 100644 index 00000000..ac4a584a Binary files /dev/null and b/muse2/doc/html/split/developer_docs/img3.png differ diff --git a/muse2/doc/html/split/developer_docs/index.html b/muse2/doc/html/split/developer_docs/index.html new file mode 100644 index 00000000..0a0f037c --- /dev/null +++ b/muse2/doc/html/split/developer_docs/index.html @@ -0,0 +1,113 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + + + + +

+ + + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/node1.html b/muse2/doc/html/split/developer_docs/node1.html new file mode 100644 index 00000000..2525890e --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node1.html @@ -0,0 +1,115 @@ + + + + + +Contents + + + + + + + + + + + + + + + + + + + + + +
+ +

+Contents +

+ + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/node10.html b/muse2/doc/html/split/developer_docs/node10.html new file mode 100644 index 00000000..c8680be0 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node10.html @@ -0,0 +1,332 @@ + + + + + +Pre-Rendering tracks + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Pre-Rendering tracks +

+ +

+The feature +

+All tracks shall be able to be "pre-renderable". Pre-rendering shall +be "layered". Pre-rendering shall act like a transparent audio cache: +Audio data is (redundantly) stored, wasting memory in order to save CPU. + +

+That is: Each track owns one or more wave-recordings of the length of +the song. If the user calls "pre-render" on a track, then this track +is played quasi-solo (see below), and the raw audio data is recorded +and stored in the "layer 0" wave recording. If the user has any effects +set up to be applied, then each effect is applied on a different layer +(creating layer 1, layer 2 etc). + +

+This means, that also MIDI and drum tracks can have effects (which +usually only operate on audio, but we HAVE audio data because of this +prerendering). + +

+Furthermore, MusE by default does not send MIDI events to the synthesizers +but instead just plays back the last layer of the prerecording (for +MIDI tracks), or does not pipe the audio data through the whole plugin +chain (causing cpu usage), but instead just plays back the last layer. +The hearable result shall be the same. + +

+Once the user changes any parameter (automation data or plugins for +wave tracks, MIDI events or effect plugin stuff for MIDI tracks), +then MusE shall generate the sound for this particular track in the +"old" way (send MIDI data to synthes, or pipe audio data through plugins). +(So that the user will not even notice that MusE actually pre-renderered +stuff.) Either MusE automatically records this while playback (if possible) +or prompts the user to accordingly set up his cabling and then record +it. Or (temporarily) disables prerecording for this track, falling back +to the plain old way of generating sound. + +

+Quasi-solo means: For wave tracks, just solo the track. For MIDI +tracks, mute all tracks which are not on the same synth (channel?), +and mute all note events which are not on the quasi-soloed track. +This causes MusE to still play any controller events from different +tracks, because they might have effects on the quasi-soloed track. (You +can have notes on channel 1 on one track and controller stuff on channel +1 on another track; then you would need quasi-solo to get proper results.) + +

+ +

+Use cases +

+ +

+Saving CPU +

+On slow systems, this is neccessary for songs with lots of, or demanding +(or both) soft synthes / plugins. Even if the synth or plugin is so +demanding that your system is not able to produce sound in real-time, +then with this feature you'll be able to use the synth (this will make +editing pretty laggish, because for a change you need to re-render at +least a part before you can listen to it, but better than being unable +to use the synth at all!) + +

+ +

+Exporting as audio project +

+Using pre-rendering on all tracks, you easily can export your project +as multi-track audio file (for use with Ardour or similar DAWs). +Just take the last layer of each track, and write the raw audio data +into the file, and you're done. (Maybe we are even able to write down +the raw-raw layer0 audio data plus information about used plugins and +settings etc..?) + +

+ +

+Mobile audio workstations +

+You might want to work a bit on your audio projects on your notebook +while you're not at home, not having access to your hardware synthesizers. +Using this feature, you could have pre-recorded the stuff in your studio +before, and now can at least fiddle around with the non-hw-synth-dependent +parts of your song, while still having your full song with you. + +

+ +

+Applying effects on MIDI tracks +

+If you have many physical audio inputs, you might already be able to +apply effect chains on MIDI tracks, by wiring the synthes' audio +outputs to your soundcard's inputs, and applying the effects on +dedicated input tracks you have to create. This requires you to have +expensive hardware, and is pretty complicated, because you need one +additional track per MIDI synth. + +

+This feature allows you to apply effects on single MIDI tracks, and not +only on full MIDI synthes, and doesn't require you to be have that +many physical audio inputs (you need to manually replug your synthes, +however). + +

+ +

+Possible scenarios +

+ +

+Setting it up +

+Create a wave track, MusE will allow you to set or unset prerendering +for every plugin in the plugin rack (recording the actual track is +useless because it would be a plain copy). +Create a MIDI track, MusE will ask you on which physical audio input +your synth is connected. Setting up multiple synthes on one physical +audio in is allowed, see below. + +

+ +

+Pre-rendering stuff +

+When the user presses the "pre-render" button, all tracks which have +been changed since their last pre-rendering will be re-rendered. +If you have multiple hardware synthes set up as they were connected +to one physical audio input port, MusE will prompt you to first plug +the proper cable in. + +

+ +

+Making changes +

+Change a note in a MIDI part, move or delete a part or change automation +parameters. MusE will temporarily disable the pre-rendered information +and instead generate the sound via sending out MIDI events, piping stuff +through effect chains or similar. If you play back the whole song, or +if you manually trigger a re-rendering of a track via the context menu, +MusE will play back the stuff, record it again and re-enable the +pre-rendered information. + +

+ +

+Extensions +

+ +

+Automatic discovery of physical audio connections +

+The user plugs all (or only some) synthes' audio outs into the available +audio inputs, then runs automatic discovery. This will send MIDI events +to each synthesizer, and look on which audio in there's activity. Then +it will assume that the synthesizer is connected to that particular +audio in. Audio ins which show activity before any MIDI events were +sent are not considered, as they're probably connected to microphones +or other noise-generating non-synthes. + +

+ +

+Audio export +

+As described in the Use cases, MusE can allow you to export your song +in some multitrack audio format. + +

+ +

+Cheap/Faked changes +

+For expensive or unavailable synthes, changing the Volume midi controller, +the Pan controller or similar "easy" controllers will not trigger a +complete re-rendering, but instead "fake" the change, by changing +the volume data directly on the recorded wave. This might require some +learning and might even get pretty complicated. + +

+ +

+Intelligent re-recording +

+For tiny changes, MusE shall only re-render the relevant part. If you +change some MIDI notes, then begin re-recording shortly before the +changes, and end re-recording as soon as the recorded stuff doesn't +differ to much from the stuff coming from the synth. Then properly +blend the old recording with the updated part. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node11.html b/muse2/doc/html/split/developer_docs/node11.html new file mode 100644 index 00000000..8c191c4b --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node11.html @@ -0,0 +1,153 @@ + + + + + +Slotted editors + + + + + + + + + + + + + + + + + + + + + + +

+Slotted editors +

+Currently, MusE has the pianoroll editor, drum editor, score editor, +then the controller editor which is inside the pianoroll/drum editor. +All these editors have a very similar concept: the "time axis" is +vertical and (almost) linear, they handle parts, and events are +manipulated similarly. + +

+A unified editor shall be created which allows you to combine different +kinds of editors in one window, properly aligned against each other. +These "different kinds of editors" shall be handled as "slots"; one +unified editor window consists of: + +

+ +

+Each slot contains the following: + +

+ +

+The main window does not show its scroll bar if there is only one slot, +because the slot's scrollbar is sufficient then. + +

+Slots can be added, destroyed, moved around, maybe even merged (if the +slot types allow it); basically, you can compare them with the staves +in the score editor. + +

+The slots shall align against each other, that is, if a score editor +slot displays a key change with lots of accidentials, then all other +slots shall either also display the key change (if they're score slots) +or display a gap. Events which happen at the same time shall be at the +same x-coordinate, regardless which slot they are. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node12.html b/muse2/doc/html/split/developer_docs/node12.html new file mode 100644 index 00000000..d73281a4 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node12.html @@ -0,0 +1,96 @@ + + + + + +Controller master values + + + + + + + + + + + + + + + + + + + + + + +

+Controller master values +

+All controllers (MIDI-controllers and also automation controllers) +shall have one set of "master values" which allow you to set a gain and +a bias. Instead of the actual set value, +$\textrm{value} * \textrm{bias}
++ textrm{bias}$ shall be sent to the MIDI device / the plugin. For +controllers like "pan", the unbiased values shall be transformed, that +is, a pan of 64, with +$\textrm{bias}=2$ and +$\textrm{gain}=0.5$, shall +be transformed to 66 (because 64 is actually 0, while 0 is actually -64). +These values shall be set in the arranger and whereever the actual +controller/automation values can be edited. + +

+


+ + + diff --git a/muse2/doc/html/split/developer_docs/node13.html b/muse2/doc/html/split/developer_docs/node13.html new file mode 100644 index 00000000..1d63ee66 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node13.html @@ -0,0 +1,79 @@ + + + + + +Enabled-indicator while recording + + + + + + + + + + + + + + + + + + + + + + +

+Enabled-indicator while recording +

+The MusE-plugin-GUIs shall display a small LED displaying whether a +controller is currently enabled or disabled. By clicking this LED, the +enabled state shall be switched. + +

+Furthermore, there shall be a dedicated window which only lets you switch +enabled/disabled states. This will be useful when using external GUIs +or the MIDI-controller-to-automation feature, to re-enable a controller +when in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode. + +

+


+ + + diff --git a/muse2/doc/html/split/developer_docs/node14.html b/muse2/doc/html/split/developer_docs/node14.html new file mode 100644 index 00000000..60af8da2 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node14.html @@ -0,0 +1,76 @@ + + + + + +Linear automation editing + + + + + + + + + + + + + + + + + + + + + + +

+Linear automation editing +

+While holding some modifier key (like shift), operating the MusE-native- +GUI sliders shall only generate control points when clicking and when +releasing the slider. This will result in linear graphs for continous +controllers, and in large steps for discrete controllers (which is in +particular useful for stuff like "which low/high-pass filter type to use"). + +

+Maybe make this behaviour default for discrete controllers? + +

+


+ + + diff --git a/muse2/doc/html/split/developer_docs/node15.html b/muse2/doc/html/split/developer_docs/node15.html new file mode 100644 index 00000000..a3388cc7 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node15.html @@ -0,0 +1,79 @@ + + + + + +Symbolic names for MIDI ports + + + + + + + + + + + + + + + + + + + + +

+
+Symbolic names for MIDI ports +

+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7"). +The mapping between these symbolic names and the hardware port (like +"ALSA midi out port") is stored in the global configuration. + +

+Song files only specify the symbolic names as the ports associated with +their tracks. No information about physical devices/port names, but only +symbolic names are stored in the song file. + +

+This resolves the issues mentioned in 1.2, and also +allows the user to share his pieces with other people: They would only +have to set up that symbolic-to-hardware mapping once (collisions are +unlikely, because an equal symbolic name should usually mean the same +device) and are happy, instead of having to re-map every port +for every song. + +

+


+ + + diff --git a/muse2/doc/html/split/developer_docs/node2.html b/muse2/doc/html/split/developer_docs/node2.html new file mode 100644 index 00000000..2c781ae7 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node2.html @@ -0,0 +1,111 @@ + + + + + +Internals - how it works + + + + + + + + + + + + + + + + + + + + + + +

+Internals - how it works +

+This chapter explains how MusE is built internally, and is meant +to be an aid for developers wanting to quickly start up with MusE. +For details on why stuff is done please refer to the following +chapter. + +

+


+ +Subsections + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/node3.html b/muse2/doc/html/split/developer_docs/node3.html new file mode 100644 index 00000000..eb89f8e7 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node3.html @@ -0,0 +1,255 @@ + + + + + +User interface programming + + + + + + + + + + + + + + + + + + + + + + +

+User interface programming +

+We use the QT Toolkit for GUI- and other programming. The QT-Assistant +is an important tool for getting help. Almost everything can be looked +up there. + +

+GUIs can be either be hardcoded (see fterfirsta`a=95 _ `a=58 : + `a>64 + `a<91 aaa + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>rranger.cpp for an example) +or can be created using QT-Designer (see the dialogs under +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>idgets/function_dialogs/ for mostly cleanly-written examples). +Don't forget to add your fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>pp, fterfirsth`h=95 _ `h=58 : + `h>64 + `h<91 hhh + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>> and fterfirstu`u=95 _ `u=58 : + `u>64 + `u<91 uuu + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>i files to the +corresponding sections in the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>MakeLists.txt! + +

+Additionally, MusE offers some custom widgets, like menu title items etc. +Following, there will be a small, unordered list about custom widgets: + +

+ +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node4.html b/muse2/doc/html/split/developer_docs/node4.html new file mode 100644 index 00000000..0c40eb93 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node4.html @@ -0,0 +1,344 @@ + + + + + +Configuration + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+
+Configuration +

+Configuration is a bit pesky in MusE in its current state. If you get +confused by reading this chapter, that's a sign of a sane mind. + +

+There are three kinds of configuration items: + +

+ +

+ +

+Reading configuration +

+fterfirstv`v=95 _ `v=58 : + `v>64 + `v<91 vvv + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>oid MusECore::readConfiguration(Xml&, bool, bool) in +fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp is the central point +of reading configuration. It is called when MusE is started first +(by fterfirstb`b=95 _ `b=58 : + `b>64 + `b<91 bbb + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ool MusECore::readConfiguration()), and also when a +song is loaded. +
It can be instructed whether to read MIDI ports (3), global configuration +and MIDI ports (1+3). Per-Song configuration is always read (2). + +

+When adding new configuration items and thus altering fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration(), +you must take care to place your item into the correct section. The code is +divided into the following sections: + +

+ +

+The sections are divided by comments (they contain --, so just +search for them). Please do not just remove code for reading obsolete entries, +but always add an appropriate entry to the 'skipping' section in order to +prevent error messages when reading old configs. + +

+ +

+Writing configuration +

+Global configuration is written using the +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration() functions, while +per-song-config is written by fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGui::MusE::writeConfiguration() +(notice the missing fterfirstG`G=95 _ `G=58 : + `G>64 + `G<91 GGG + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lobal; both implemented in fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>onf.cpp). + +

+fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteConfiguration is actually just a subset of the code in +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. Duplicate code! +

+ +

+Song state +

+Additionally to per-song configuration, there is the song's state. +This contains "the song", that is all tracks, parts and note events, +together with information about the currently opened windows, their +position, size, settings and so on. Adding new items here is actually +pretty painless: Configuration is read and written using +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usECore::Song::read and fterfirst:`:=95 _ `:=58 : + `:>64 + `:<91 ::: + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>:write, both implemented in +fterfirsts`s=95 _ `s=58 : + `s>64 + `s<91 sss + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ongfile.cpp. There are no caveats. + +

+ +

+How to add new items +

+When adding global configuration items, then add them into the second +block ("global configuration") in fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration and into +fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+When adding just-per-song items, better don't bother to touch the +"configuration" code and just add it to the song's state (there might +be rare exceptions). + +

+When adding global configuration items, make sure you add them into the +correct section of fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>eadConfiguration, and into fterfirstw`w=95 _ `w=58 : + `w>64 + `w<91 www + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>riteGlobalConfiguration. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node5.html b/muse2/doc/html/split/developer_docs/node5.html new file mode 100644 index 00000000..4803252d --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node5.html @@ -0,0 +1,860 @@ + + + + + +User controls and automation + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+User controls and automation +

+ +

+Handling user input +

+ +

+Plugins and synthesizers +

+ +

+Overview +

+When the user launches a plugin's GUI, either a MusE-window with +the relevant controls is shown, or the native GUI is launched. MusE +will communicate with this native GUI through OSC (Open Sound Control). +The relevant classes are fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginGui, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase +(in fterfirstp`p=95 _ `p=58 : + `p>64 + `p<91 ppp + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>lugin.h) and fterfirstO`O=95 _ `O=58 : + `O>64 + `O<91 OOO + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>scIF (in fterfirsto`o=95 _ `o=58 : + `o>64 + `o<91 ooo + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>sc.h). + +

+If the user changes a GUI element, first the corresponding control is +disabled, making MusE not steadily update it through automation +while the user operates it. Then MusE will update the plugin's parameter +value, and also record the new value. When appropriate, the controller +is enabled again. + +

+ +

+Processing the input, recording +

+Upon operating a slider, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginIBase::setParam is called, +which usually writes the control change into the ringbuffer +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. (fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::apply(), +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::getData() will read this ringbuffer and +do the processing accordingly). Furthermore, fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::recordAutomation +is called, which either directly modifies the controller lists or writes +the change into a "to be recorded"-list (fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents) +(depending on whether the song is stopped or played). + +

+The fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_recEvents list consists of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal +items (see fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trl.h), which hold the following data: + +

+It is processed when the song is stopped. The call path for this is: +fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::stopRolling calls fterfirstS`S=95 _ `S=58 : + `S>64 + `S<91 SSS + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ong::processAutomationEvents +calls fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::processAutomationEvents. +This function removes the old events from the track's controller list +and replaces them with the new events from fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>recEvents. In +fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, just all controller events within the recorded +range are erased; in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH mode, the fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_START +and fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>RVT_STOP types of the fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlRecVal events are used +to determine the range(s) which should be wiped. + +

+ +

+How it's stored +

+Automation data is kept in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continuous (a new control +point results in the value slowly sloping to the new value). +Furthermore, it stores a fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>curVal (accessed by fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>urVal()), +which holds the currently active value, which can be different from the +actually stored value because of user interaction. This value is also +used when there is no stored automation data. + +

+fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::addController and fterfirstr`r=95 _ `r=58 : + `r>64 + `r<91 rrr + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>emoveController are used to add/remove whole controller types; the most important functions which +access fterfirst_`_=95 _ `_=58 : + `_>64 + `_<91 ___ + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>controller are: + +

+ +

+Whenever a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList has been manipulated, +fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChange(Track*) shall be called, +which emits the fterfirstM`M=95 _ `M=58 : + `M>64 + `M<91 MMM + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>usEGlobal::song->controllerChanged(Track*) +signal in order to inform any parts of MusE about the change (currently, +only the arranger's part canvas utilizes this). + +

+ +

+Enabling and disabling controllers +

+Disabling the controller is both dependent from the current automation +mode and from whether the GUI is native or not. +In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode, once a slider is touched (for MusE-GUIs) or +once a OSC control change is received (for native GUIs), the control +is disabled until the song is stopped or seeked. + +

+In fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_TOUCH (and currently (r1492) fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_READ, but +that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the +corresponding control is disabled. Once the slider is released, the +control is re-enabled again. Checkboxes remain in "disabled" mode, +however they only affect the recorded automation until the last toggle +of the checkbox. (Example: start the song, toggle the checkbox, toggle +it again, wait 10 seconds, stop the song. This will NOT overwrite the +last 10 seconds of automation data, but everything between the first +and the last toggle.). For native GUIs, this is a bit tricky, because +we don't have direct access to the GUI widgets. That is, we have no +way to find out whether the user doesn't touch a control at all, or +whether he has it held down, but just doesn't operate it. The current +behaviour for native GUIs is to behave like in fterfirstA`A=95 _ `A=58 : A + <`<=95 _ `<=58 : < + u@nderscorehyph<271>>UTO_WRITE mode. + +

+The responsible functions are: fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::oscControl and +fterfirstD`D=95 _ `D=58 : + `D>64 + `D<91 DDD + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>ssiSynthIF::oscControl for handling native GUIs, +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::ctrlPressed and fterfirstc`c=95 _ `c=58 : + `c>64 + `c<91 ccc + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlReleased for MusE +default GUIs and fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::guiParamPressed, +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParamReleased, fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderPressed and +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSliderReleased for MusE GUIs read from a UI file; +fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiSlider* obviously handle sliders, while fterfirstg`g=95 _ `g=58 : + `g>64 + `g<91 ggg + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>uiParam* +handle everything else which is not a slider. They call +fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableController to enable/disable it. + +

+Furthermore, on every song stop or seek, fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::enableAllControllers +is called, which re-enables all controllers again. The call paths for +this are: + +

+ +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node6.html b/muse2/doc/html/split/developer_docs/node6.html new file mode 100644 index 00000000..a06c25f8 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node6.html @@ -0,0 +1,82 @@ + + + + + +Design decisions + + + + + + + + + + + + + + + + + + + + + + +

+Design decisions +

+

+ +Subsections + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/node7.html b/muse2/doc/html/split/developer_docs/node7.html new file mode 100644 index 00000000..100e7430 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node7.html @@ -0,0 +1,234 @@ + + + + + +Automation + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Automation +

+As of revision 1490, automation is handled in two ways: User-generated +(live) automation data (generated by the user moving sliders while playing) +is fed into fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. Automation data is kept +in fterfirstA`A=95 _ `A=58 : + `A>64 + `A<91 AAA + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>udioTrack::_controller, which is a fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlListList, +that is, a list of fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlList also stores whether the list is meant discrete +(a new control point results in a value-jump) or continous (a new control +point results in the value slowly sloping to the new value). + +

+While fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo can be queried very quickly and +thus is processed with a very high resolution (only limited by the +minimum control period setting), the automation value are expensive to +query, and are only processed once in an audio driver period. +This might lead to noticeable jumps in value. + +

+This could possibly be solved in two ways: + +

+Maintaining a slave control list +

+This approach would maintain a fully redundant slave control list, +similar to fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo. This list must be updated +every time any automation-related thing is changed, and shall contain +every controller change as a tuple of controller number and value. +This could be processed in the same loop as fterfirstP`P=95 _ `P=58 : + `P>64 + `P<91 PPP + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>luginI::_controlFifo, +making it comfortable to implement; furthermore, it allows to cleanly +offer automation-settings at other places in future (such as storing +automation data in parts or similar). + +

+ +

+Holding iterators +

+We also could hold a list of iterators of the single fterfirstC`C=95 _ `C=58 : + `C>64 + `C<91 CCC + + <`<=95 _ `<=58 : + `<>64 + `<<91 <<< + + c@amelhyph<269>>trlLists. +This would also cause low CPU usage, because usually, the iterators only +need to be incremented once. However, it is pretty complex to implement, +because the iterators may become totally wrong (because of a seek in the +song), and we must iterate through a whole list of iterators. + +

+ +

+Just use the current data access functions +

+By just using the current functions for accessing automation data, +we might get a quick-and-dirty solution, which however wastes way too +much CPU ressources. This is because on every single frame, we +need to do a binary search on multiple controller lists. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/developer_docs/node8.html b/muse2/doc/html/split/developer_docs/node8.html new file mode 100644 index 00000000..505fb7c7 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node8.html @@ -0,0 +1,125 @@ + + + + + +Feature requests + + + + + + + + + + + + + + + + + + + + + +

+Feature requests +

+

+ +Subsections + + + +

+ + + diff --git a/muse2/doc/html/split/developer_docs/node9.html b/muse2/doc/html/split/developer_docs/node9.html new file mode 100644 index 00000000..dea45e82 --- /dev/null +++ b/muse2/doc/html/split/developer_docs/node9.html @@ -0,0 +1,72 @@ + + + + + +Per-Part automation and more on automation + + + + + + + + + + + + + + + + + + + + + + +

+Per-Part automation and more on automation +

Automation shall be undo-able. Automation shall reside in parts which +are exchangeable, clonable etc (like the MIDI- and Wave-Parts). +Global per-synth/per-audiotrack automation shall also be available, but +this can also be implemented as special case of part automation (one +long part). + +

+


+ + + diff --git a/muse2/doc/html/split/documentation/arrow_tool.png b/muse2/doc/html/split/documentation/arrow_tool.png new file mode 100644 index 00000000..1ae872fb Binary files /dev/null and b/muse2/doc/html/split/documentation/arrow_tool.png differ diff --git a/muse2/doc/html/split/documentation/documentation.css b/muse2/doc/html/split/documentation/documentation.css new file mode 100644 index 00000000..17bee66c --- /dev/null +++ b/muse2/doc/html/split/documentation/documentation.css @@ -0,0 +1,35 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ +DIV.navigation { } +DIV.center { } +SPAN.textit { font-style: italic } +SPAN.arabic { } +SPAN.textbf { font-weight: bold } diff --git a/muse2/doc/html/split/documentation/documentation.html b/muse2/doc/html/split/documentation/documentation.html new file mode 100644 index 00000000..824bf5f6 --- /dev/null +++ b/muse2/doc/html/split/documentation/documentation.html @@ -0,0 +1,196 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + + + + + +
+ +

+
+ +
Image muse2 + +
+

+ + + + + +

+ + + diff --git a/muse2/doc/html/split/documentation/img1.png b/muse2/doc/html/split/documentation/img1.png new file mode 100644 index 00000000..36e71d7e Binary files /dev/null and b/muse2/doc/html/split/documentation/img1.png differ diff --git a/muse2/doc/html/split/documentation/index.html b/muse2/doc/html/split/documentation/index.html new file mode 100644 index 00000000..824bf5f6 --- /dev/null +++ b/muse2/doc/html/split/documentation/index.html @@ -0,0 +1,196 @@ + + + + + +MusE Documentation + + + + + + + + + + + + + + + + + + + +
+ +

+
+ +
Image muse2 + +
+

+ + + + + +

+ + + diff --git a/muse2/doc/html/split/documentation/main_window_add_track.png b/muse2/doc/html/split/documentation/main_window_add_track.png new file mode 100644 index 00000000..7750ca7f Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_add_track.png differ diff --git a/muse2/doc/html/split/documentation/main_window_annotated.png b/muse2/doc/html/split/documentation/main_window_annotated.png new file mode 100644 index 00000000..f8f7701f Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_annotated.png differ diff --git a/muse2/doc/html/split/documentation/main_window_with_arrangement.png b/muse2/doc/html/split/documentation/main_window_with_arrangement.png new file mode 100644 index 00000000..8d391d9f Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_with_arrangement.png differ diff --git a/muse2/doc/html/split/documentation/main_window_with_automation.png b/muse2/doc/html/split/documentation/main_window_with_automation.png new file mode 100644 index 00000000..3930c0da Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_with_automation.png differ diff --git a/muse2/doc/html/split/documentation/main_window_with_midi_automation.png b/muse2/doc/html/split/documentation/main_window_with_midi_automation.png new file mode 100644 index 00000000..5357a6d3 Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_with_midi_automation.png differ diff --git a/muse2/doc/html/split/documentation/main_window_with_midi_editor_vam.png b/muse2/doc/html/split/documentation/main_window_with_midi_editor_vam.png new file mode 100644 index 00000000..bedf6250 Binary files /dev/null and b/muse2/doc/html/split/documentation/main_window_with_midi_editor_vam.png differ diff --git a/muse2/doc/html/split/documentation/midi_config_window.png b/muse2/doc/html/split/documentation/midi_config_window.png new file mode 100644 index 00000000..f979ad34 Binary files /dev/null and b/muse2/doc/html/split/documentation/midi_config_window.png differ diff --git a/muse2/doc/html/split/documentation/midi_routing_matrix.png b/muse2/doc/html/split/documentation/midi_routing_matrix.png new file mode 100644 index 00000000..ac080a92 Binary files /dev/null and b/muse2/doc/html/split/documentation/midi_routing_matrix.png differ diff --git a/muse2/doc/html/split/documentation/mixer.png b/muse2/doc/html/split/documentation/mixer.png new file mode 100644 index 00000000..22d9f2b7 Binary files /dev/null and b/muse2/doc/html/split/documentation/mixer.png differ diff --git a/muse2/doc/html/split/documentation/mixer_with_one_input.png b/muse2/doc/html/split/documentation/mixer_with_one_input.png new file mode 100644 index 00000000..629328d7 Binary files /dev/null and b/muse2/doc/html/split/documentation/mixer_with_one_input.png differ diff --git a/muse2/doc/html/split/documentation/mixer_with_one_input_buttons.png b/muse2/doc/html/split/documentation/mixer_with_one_input_buttons.png new file mode 100644 index 00000000..c6ad7b0c Binary files /dev/null and b/muse2/doc/html/split/documentation/mixer_with_one_input_buttons.png differ diff --git a/muse2/doc/html/split/documentation/muse2.png b/muse2/doc/html/split/documentation/muse2.png new file mode 100644 index 00000000..84a28d8a Binary files /dev/null and b/muse2/doc/html/split/documentation/muse2.png differ diff --git a/muse2/doc/html/split/documentation/no_audio.png b/muse2/doc/html/split/documentation/no_audio.png new file mode 100644 index 00000000..1e62245c Binary files /dev/null and b/muse2/doc/html/split/documentation/no_audio.png differ diff --git a/muse2/doc/html/split/documentation/node1.html b/muse2/doc/html/split/documentation/node1.html new file mode 100644 index 00000000..e78bf648 --- /dev/null +++ b/muse2/doc/html/split/documentation/node1.html @@ -0,0 +1,146 @@ + + + + + +Contents + + + + + + + + + + + + + + + + + + + + + +
+ +

+Contents +

+ + + + +

+ + + diff --git a/muse2/doc/html/split/documentation/node10.html b/muse2/doc/html/split/documentation/node10.html new file mode 100644 index 00000000..de0bcc14 --- /dev/null +++ b/muse2/doc/html/split/documentation/node10.html @@ -0,0 +1,265 @@ + + + + + +Automation + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+
+Automation +

+Automation is the ability to record (or construct) and playback +exact sequences of control movements. + +

+MIDI and audio automation are each currently uniquely different, +but share some similarities. + +

+ +

+
+Audio automation +

+Almost all graphical audio controls in MusE can be automated. + +

+This includes an audio track's volume and pan, and the controls +of any plugins in the effects rack, and if the track is a +synthesizer track, all of the synth's controls. + +

+Each control has a manual adjustment value. This value is shown +when there is no automation data at all, or automation has been +disabled. + +

+For plugin and synth controls, it is usually more desirable to +manipulate automation with the generic plugin GUIs, because +MusE has full control over their behaviour. (See plugin GUIs +2.6.1). + +

+There are a few ways to enter audio automation data: + +

+

+Audio automation modes +

+Each audio track strip has an automation mode button +at the bottom. There are four automation modes: +
+
OFF:
+
Disables all automation, uses manual value always. +
+
READ:
+
Automation data is applied to controls. If any +automation data exists, the manual value is overridden and has +no effect. +
+
TOUCH:
+
Allows you to alter a control at any time, while +transport is stopped or rolling, If rolling, when the control is +released it returns to reading from automation data. +
+
WRITE:
+
Allows to adjust an initial value before rolling +the transport. While rolling, when the control is released it does +not return to reading from automation data. +
+
+Here is a screenshot of automation WRITE mode, and some automation +data, with the track pane automation popup menu showing (see track +automation 2.3.1): + +
+ + + +
Figure 2.11: +Audio automation graphs
+
+ +
Image main_window_with_automation
+
+ +

+ +

+Midi automation +

+MIDI automation is a slightly different concept: Unlike audio +automation, currently there is no automation 'mode' and it doesn't +record graphical control movements. Data is viewed from within +the pianoroll and drum editors, by clicking on the 'Ctrl' button +on those canvases. + +

+Similar to audio controls, each midi control has a manual adjustment +value. This value is overridden when there is midi automation data. + +

+There are a few ways to enter MIDI automation data: + +

+Here is a screen shot of a midi track, containing a midi part +which has been opened with the pianoroll editor and automation +data showing. + +

+The 'Ctrl' popup menu (bottom left) shows available midi controllers +and the green dot indicates there is some data. + +

+ +

+ + + +
Figure 2.12: +MIDI automation graphs
+
+ +
Image main_window_with_midi_automation
+
+ +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node11.html b/muse2/doc/html/split/documentation/node11.html new file mode 100644 index 00000000..5f9e3bf9 --- /dev/null +++ b/muse2/doc/html/split/documentation/node11.html @@ -0,0 +1,259 @@ + + + + + +Configuration + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Configuration +

+ +

+ +

+MIDI ports +

+MIDI ports provide an abstraction layer for your MIDI hardware and +synthesizers (which can be both software and hardware synthesizers), +and other MIDI applications. Port are numbered. In order to produce +sound, each MIDI track is assigned to exactly one MIDI port, to which +the MIDI events are then sent. + +

+The advantage of this abstraction layer is that if your system changes, +for example you change MIDI hardware, then you need only modify the +ports instead of all the tracks using those ports. This is similar +to the audio input and output track abstraction to the outside world. + +

+ +

+MIDI port configuration +

+In the midi/softsynth configuration menu, you must map the port numbers +to the actual devices (by selecting ALSA or jack midi ports, or synth +plugins). + +

+Try left-clicking on the "Ports" column of some MIDI track. +If you use a soft synth, right-clicking the Ports column of the synth +or any track using the synth lets you launch the synth's GUI. + +

+ +

+ + + +
Figure 2.13: +Midi configuration window
+
+ +
Image midi_config_window
+
+ +

+ +

+Columns in the MIDI configuration ports list: +

+
+
GUI:
+
For synthesizer devices, indicates if a gui is available +and if it is showing. Click to show. +
+
I:
+
If present, the port can accept MIDI input. Click to +enable or disable it. +
+
O:
+
If present, the port can send MIDI output. Click to enable +or disable it. +
+
Instrument:
+
Selects the instrument to be used when MIDI is +played through the port. +
+
Device name:
+
Selects or creates a MIDI device assigned to the +port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is +enabled), or soft synthesizers. Jack MIDI devices are created by selecting +Create Jack Device from the Device name drop-down menu. Jack MIDI devices +can be renamed as you wish by clicking the device name. Soft synthesizers +are created by clicking in the soft synthesizer list and then Add +Instance. Or you can simply create a new synthesizer track from the +arranger track list, or even the mixer menus. +
+
In and Out routes:
+
These are for Jack MIDI devices, they are +the routes to and from available Jack MIDI ports. Jack may provide +different alias names for these ports, you can select which alias +is shown. +
+
Default in channels:
+
Auto-connect these port channels to +new midi or drum tracks. +
+
Default out channel:
+
Auto-connect new midi or drum tracks +to this channel on the port. +
+
State:
+
Indicates the state of the port including any errors +opening it. +
+
+ +

+ +

+Global settings +

+ +

+Audio settings +

+ +

+Minimum control period +

+Plugins can usually process an arbitrarily small (or large) amount +of samples. If some plugin control value changes continously, to provide +ideal listening experience, MusE would need to call the plugin 44100 +times a second, asking for one single value at a time. With the minimum +control period setting, the user can force MusE to ask the plugin for +at least N values. Setting this value to 64 would in this situation +make MusE call the plugin +$689=\frac{44100}{64})$ times a second, +asking for 64 values at a time. While doing this will reduce accuracy +of control changes, it may also reduce CPU usage, because calling +the plugin more often, requesting smaller chunks, is more expensive +than calling it seldomly, requesting larger chunks. + +
+Recommendation +
+If you have no performance problems, or if you want to do the final +downmix of your project, set this to a low value. If you're experiencing +performance problems, increasing this value might help. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node12.html b/muse2/doc/html/split/documentation/node12.html new file mode 100644 index 00000000..cffda841 --- /dev/null +++ b/muse2/doc/html/split/documentation/node12.html @@ -0,0 +1,75 @@ + + + + + +Appendix + + + + + + + + + + + + + + + + + + + + + +

+ +
+Appendix +



+ +Subsections + + + +

+ + + diff --git a/muse2/doc/html/split/documentation/node13.html b/muse2/doc/html/split/documentation/node13.html new file mode 100644 index 00000000..4c92aa47 --- /dev/null +++ b/muse2/doc/html/split/documentation/node13.html @@ -0,0 +1,222 @@ + + + + + +Understanding the effects rack + + + + + + + + + + + + + + + + + + + + +

+Understanding the effects rack +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+MusE will try to internally create as many independent copies +(instances) of a plugin as necessary, to satisfy the number of channels +in the audio track. +Basically it divides the number of track channels by the number of +plugin audio inputs or outputs to determine how many copies to make. +First it examines the number of plugin audio outputs, and if there are +none, it will examine the number of audio inputs, and if there are +none, it will simply use just one plugin copy. + +

+For mono tracks with plugins having more than one audio input or +output, MusE uses the first input or output and ignores the rest. + +

+For stereo tracks: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
plugin inputsoutputscopiestrack in route channelstrack out route channels
00100
01202
0>=2102
10220
11222
1>=211 (L only)2
>=20120
>=21222
>=2>=2122
+ +

+Notice that on a stereo track with a plugin having one audio input and +two audio outputs, only the first track input route channel is used +(left only). + +

+These same rules apply to inter-plugin audio when more than one plugin +is in the rack chain. Extra audio outputs of one plugin may be ignored +by the next plugin if not used. + +

+Currently specialized plugins with many inputs and/or outputs are not +really useful in MusE. + +

+Nor are so-called 'realtime' control plugins which use audio inputs +and outputs for control signals. + +

+Loud noise alert! Beware of using such plugins in an audio effects +rack. + +

+Example: Consider a stereo Audio Input track with these effect rack + LADSPA plugins: + +

+ +

+ +

+The Comb Splitter has one audio input and two audio outputs. +The Stereo Echo has two audio inputs and two audio outputs. + +

+The stereo Audio Input track will therefore ignore its second +input route connection. It will process the left input only, +separating it into stereo with the Comb Splitter, passing the +split stereo signal into the Stereo Echo, finally producing +stereo output available at the Audio Input track's output routes. + +

+One improvement would be not creating unused redundant plugin copies +between plugins in stereo tracks. +For example, for a plugin having one audio input and one audio output, +feeding a plugin having one audio input and two audio outputs, +the extra copy of the first plugin is redundant and not required, +but currently it is created anyway. + +

+ + + + diff --git a/muse2/doc/html/split/documentation/node2.html b/muse2/doc/html/split/documentation/node2.html new file mode 100644 index 00000000..52fa56a6 --- /dev/null +++ b/muse2/doc/html/split/documentation/node2.html @@ -0,0 +1,74 @@ + + + + + +What is this? + + + + + + + + + + + + + + + + + + + + + + +

+What is this? +

+You are, if you have printed this document, holding in your hand the +written documentation for the audio and midi sequencer MusE version 2. +
http://www.muse-sequencer.org is MusE's home on the internet where +everything MusE releated should be possible to find, software, this +documentation, forums, mailing lists, bug reporting, FAQs. If you have +this document but not the software head on over there to find what it's +all about. +

+ + + diff --git a/muse2/doc/html/split/documentation/node3.html b/muse2/doc/html/split/documentation/node3.html new file mode 100644 index 00000000..ad9b33a9 --- /dev/null +++ b/muse2/doc/html/split/documentation/node3.html @@ -0,0 +1,231 @@ + + + + + +User's manual + + + + + + + + + + + + + + + + + + + + + + +

+User's manual +

+ +

+


+ +Subsections + + + +

+ + + diff --git a/muse2/doc/html/split/documentation/node4.html b/muse2/doc/html/split/documentation/node4.html new file mode 100644 index 00000000..ec5899e3 --- /dev/null +++ b/muse2/doc/html/split/documentation/node4.html @@ -0,0 +1,591 @@ + + + + + +Introduction + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Introduction +

+ +

+A brief history of computer audio and MusE +

+To quickly summarize over a decades open source development: in 1999 Werner + Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first +few releases (actually not few, Werner relentlessly churned out new releases) +MusE was only a midi sequencer. The target was to create a fully fledged +midi sequencer for the Linux operating system. Over the years audio was +added among with other things implemented and sometimes abandoned. +Today MusE is a stable and feature rich music creation environment which +strives to encompass most of the music recording process, creation, editing, +mastering. + +

+ +

+Definitions +

+CTRL refers to the control key on the keyboard, e.g. CTRL+C +means to press and hold the control key while pressing the c key. Make sure +you know where you have it so you won't accidentally lose control +(bad jokes are the best jokes, so say we all!). +
SHIFT refers to the shift key on the keyboard, see above for usage +
ALT refers to the alt key on the keyboard, see above for usage +
$> is used as a generic definition for a terminal prompt. When the +manual lists a command that shall be typed, the prompt is not part of the +command. +
+Keys are always referred to in bold uppercase, e.g. A. For instance +SHIFT+A for the key a pressed together with the shift key. +
+Sometimes terminal examples are written tabbed in with a fixed font to +visualize more closely what something looks like on the screen. +E.g. +
$> muse2 +
+

+ +

+Getting up and running for impatient people +

+Install MusE from the repository of your chosen distribution. +To get decent performance start http://jackaudio.org/Jack with +the following command in a terminal: +
$> jackd -d alsa -d hw:0 -p 256 +
+Or, if you prefer, use the launcher utility +http://qjackctl.sourceforge.net/QJackCtl to get some +help starting Jack. +After this, start MusE from the menu or fire up another terminal and +type + +

+muse2. +
+If this didn't work out read on for the slightly more complete route for +getting things started. + +

+ +

+Getting up and running +

+ +

+Installation from binaries +

+There are several ways to install MusE depending on your situation. The +most convenient way is to install a prepackaged version from your chosen +distribution. The drawback of this is that it may not be the most recent +version, though often there is a more recent package from a private packager. + +

+Installation from source +

+Building MusE from source is not hard, there are a number of prerequistes +that must be met but the actual building should be painless (ha, famous +last words). +
+Please follow the README in the source package and/or read the instructions +on the homepage: http://muse-sequencer.org/index.php/Installation +

+ +

+Hardware +

+MusE on the Linux platform supports midi through ALSA and Jack-midi and audio +through Jack. For information on what hardware is supported there are some +convenient places to check: + + +Also, as is often a very good approach for Linux and open source, the +various forums available on the internet often contain good information. +Chances are someone has already tried your configuration and/or had your +specific problem and the solution is already written down. + +

+Launching +

+After installation the binary muse2 is installed on the computer. If MusE +was installed from a distribution repository the binary may have a +different name depending on the distribution policies. Most distributions +do however install a menu entry so MusE should be conveniently available +from there. + +

+Audio preconditions +

+In the standard case MusE expects to find and connect to the Jack audio +server http://jackaudio.org. Make sure jack is installed (if MusE was +installed with a distribution-package Jack will very likely already be +installed) For Jack to run with best performance your system should be +sufficiently tuned to allow it to run with realtime capabilities. The +realtime configuration is configuration of the operating system and roughly +consists of two parts. + +
    +
  1. By default on most distros only the superuser lets applications setup +realtime capabilities. Please see the APPENDIX for setting up realtime +
  2. +
  3. Maximizing performance. A standard linux installation may not able +to reach the performance required by a power user. This requires exchanging +the linux kernel for a so called lowlatency kernel, this is also covered by +the realtime APPENDIX. +
  4. +
+ +

+ +

+Running MusE +

+Find MusE in the menu or open a terminal and enter muse2. + +

+$> muse2 +
+A splash screen should pop up followed +by the main application window and you are off! +
+If an error like the screenshot below pops up the Jack audio server is +either not running or started as a different user than what you are trying +to start MusE as. + +

+ + + +
Figure 2.1: +Jack server missing
+
+ +
Image no_audio
+
+ +

+Midi only +

+MusE can be started in Midi-only mode where MusE does not have any external +dependencies apart from ALSA midi. In this case start MusE from a terminal: +$> muse2 -a + +

+ +

+ALSA midi with Jack +

+If Jack is running, by default MusE will not use ALSA devices, preferring +Jack midi instead. To force ALSA devices to be used as well as Jack +midi, start MusE with the -A option: $> muse2 -A + +

+ +

+Beginners tutorial +

+To get a quick grip of what MusE can achieve please follow this beginners +tutorial. + +

+Midi Setup +

+First off, fire up MusE as was described in the previous chapter, making +sure that the jack audio server is started with sufficient configuration +to allow for audio output without breakup. Also make sure your system can +make sound. + +

+Soft synth test +

+With MusE up and running right click in the Track-pane (see +Fig. 2.8) and select +Add Synth > MESS > vam soft synth. +A Soft Synth track called vam-0 should appear as well as a separate GUI +for the synthesizer. + +

+Now right click once more in the Track-pane and select Add Midi +Track. Another track appears called Track 1, and its track list Port +column should show it is bound to the synth that was just created vam-0. +If it is not, click on the Track 1 Port column to open a drop-down list +of available devices and choose vam-0. + +

+ +

+r0.05 +Image arrow_tool + +
+Now select the drawing tool icon +from the toolbar, alternatively press the shortcut key D. +Move the mouse over to the arranger canvas as referenced in +Fig. 2.8 +and point at the midi track, the mouse should have changed to a small pencil. +Draw a Part along the midi track using the mouse. For this exercise it is +not important where or how large the drawn Part is. When you are done double +click on the drawn part. This will open up the Piano Roll editor. To the +left of the Piano Roll there are piano keys in a vertical line, try clicking +on the keys in this virtual keyboard each click should be rewarded with a +synth sound (maybe of questionable quality, a sound nevertheless) + +
+ + + +
Figure 2.2: +vam synthesizer
+
+ +
Image vam_synth
+
+ +

+ +

+Missing sound +

+If you got sound from the previous exercise you can carry on to the next, +or keep reading for further enlightenment in case you come upon trouble +later on. If there is no sound we need to do some fault hunting. First +off, click on Arranger window once more and select the vam-0 track in the +track-pane. + +
+ + + +
Figure 2.3: +Midi editor view
+
+ +
Image main_window_with_midi_editor_vam
+
+Now bring back Piano Roll window and align the windows so you +can see the piano keys as well as the Meter on the Mixer Strip (see the +5 Function by function chapter for more information on these windows). +The result should be something like the following: + +

+When pressing one of the keys on virtual Keyboard the Meter on the Mixer +Strip should light up in green to visualize that the Synth is making +sound, if it is not try to trace back your steps and and see if you did +anything differently than described. +Now, if the Meter lights up but there is still no sound we need to +check the routing between the tracks. Click on the Arranger window again +and select the Out 1 track, this is the predefined output which MusE by +default loads at startup, at the bottom of Mixer Strip there are two +buttons looking like tele- jacks, these bring up the inputs and outputs +of the track, click on the right one, the output and make sure that it is +connected to some valid outputs on your system. + +

+r0.25 +Image output_routing + +
+Click on the outputs to select them, if you did changes here go back and +try clicking on the Piano Roll keyboard again, hopefully it helped. If there +still are problems make sure your system actually can make sound through +Jack, this is however getting outside the scope of this manual. +
+
This might be the time to bring up the concept of community support. +Open source software could never be what it is without the support given by +individuals on forums and mailinglists, if the information given in this +document is not enough, try googling your problem and/or get in touch with +one of the online forums for MusE or Linux audio in general. See some pointers +in the Support chapter. + +

+ +

+Recording Midi +

TBD + +

+Recording Audio +

+At this point we'll make a a slight detour into full on audio recording. Getting +audio out of MusE has already been covered in the previous chapters so we will +concentrate on the additional steps needed to record onto an audio track. +
+
+When MusE is first fired up, the +output track has already been created (more about this in the chapter about +templates), to proceed with audio recording we need to add two additional tracks, a +wave track and an input track. +
+When MusE is first started right click in an empty space on the track view + +
+ + + +
Figure 2.4: +Add track
+
+ +
Image main_window_add_track
+
+and select Add Audio Input. Right click again and also select +Add Wave Track. Two additional tracks are now visible in the Arranger, +"Input 1" and "Track 1", bring up the mixer with F10 and you should see +the following configuration. + +
+ + + +
Figure 2.5: +Mixer with one input
+
+ +
Image mixer_with_one_input
+
+ +
+Note the buttons on each mixer strip. hover over them to see their +functionality. For more information on all the buttons see coming chapters +about the mixer. For now lets just do what we must. +
+1. click on the stereo symbol over the slider to change the input to a mono track. +
+2. do the same for the wave track (optional) +
+3. click on the Mute (gray speaker) icon on the input track to unmute it. +
+4. click on the input routing button (see the tooltip, it looks like a tele plug) +on the input track and select an appropriate connection from your system. +
+5. click on the output routing button on the input track and select +Track 1 +
+
+Already after the meter on the input track should be able to display that there +is incoming sound from your sound source. If there actually is sound coming +from your sound source, that is. +
+We are now nearly ready to start recording. First we need to select a location +to store the files. MusE does not use a centralized storage of soundfiles but +uses the path of the song-file (extension .med) as guidance as to where the +audio files should be placed. Now as it happens MusE will prohibit us from +starting a recording until the songfile has been stored. So lets take advantage +of this behaviour and just go ahead and try to record. Let's get started. +
+In the mixer click on the red record dot on the Audio Track to arm it +for recording (or enable if you will). Now when there is audio coming into the +input it will also show up on the Audio Track. Also note that all the input and +output routing buttons on the tracks now have the same gray color, this means +that all of the tracks have a proper connection. + +
+ + + +
Figure 2.6: +Mixer buttons
+
+ +
Image mixer_with_one_input_buttons
+
+ +
+All fine and dandy. Now bring up the arranger window and find the round, red on +white record button and click on it. This is your queue to MusE to +prepare for recording. However since we have not saved our song we are presented +with a dialog to do just that. +
+
+ + + +
Figure 2.7: +Save song
+
+ +
Image project_my_first_song
+
+Note the check box for creating a project folder, when working with audio this +is very much recommended or you may soon loose track of what audio files belong +to which song. +
+Finally we are ready to start recording! The process is completed by clicking +on the Play button in the Arranger. If all went well MusE then starts +to record a wave file from the Input Track placed in your song directory. +
+When you wish to stop recording press Stop in the Arranger, now the +resulting waveform should be visible in the Arranger. After rewinding the Play +position and pressing Play again the resulting sound should be audible +through the connected output. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node5.html b/muse2/doc/html/split/documentation/node5.html new file mode 100644 index 00000000..8afdca00 --- /dev/null +++ b/muse2/doc/html/split/documentation/node5.html @@ -0,0 +1,209 @@ + + + + + +Basic overview + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Basic overview +

+In this section we will make a step by step walk-through of all the +different editors, their purpose and what functions they support. + +

+ +

+Main/Arranger +

+ +

+ + +

+ + + +
Figure 2.8: +MusE main window
+
+ +
Image main_window_annotated
+
+Above is the main window of MusE, the Arranger, this is what greets you +when launching MusE. The Arranger consists of two main parts, the Track-pane +and the Arranger canvas. The Track-pane lists all currently visible tracks +and the Arranger canvas contains all Parts of the composition. The +screenshot above shows an empty project. Below is MusE with a song in +progress, turns out it wasn't a very good song, but for our purposes it +is fine. In the below screenshot there are a lot of tracks visible in the +Track-pane, each have an icon which indicate it's type, wave-track, input, +output etcetera, more about that later. In the Arranger canvas a number of +parts are visible, the ones in yellow are in this composition wave files, +the multicolored line are different Parts of a drum track. + +

+ +

+ + + +
Figure 2.9: +MusE main window with arrangement
+
+ +
Image main_window_with_arrangement
+
+ +

+ +

+
+Mixer +

+Choosing View > Mixer A or B from the menu in the main +window will bring up the mixer as viewed below. The mixer will open with +all options enabled, showing channel strips for all tracks in the current +setup, depending on how far you have gotten this view may become very large, +at which point it may be a good idea to limit what is viewed in the Mixer. +From the view menu all the different kinds of tracks can be toggled on/off +from the mixer. Some may find it a good idea to use the two mixers A and B +setup with different setup and store this in your song template(s), more +about this in the Song Template section. It can be argued that everything +in MusE is a track analogous to the Unix idiom that everything is a file. +The types of tracks visible in the mixer (and track-pane) are: + +
+r0.5 +Image mixer + +
+ + + +

+There is also a Midi Track variation called Drum Track, they are +however not distinguishable from Midi Tracks in the Mixer. Also the +strips for midi tracks are different in the Mixer than in the +Track-pane view. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node6.html b/muse2/doc/html/split/documentation/node6.html new file mode 100644 index 00000000..179d86b6 --- /dev/null +++ b/muse2/doc/html/split/documentation/node6.html @@ -0,0 +1,489 @@ + + + + + +Tracks and parts + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+Tracks and parts +

+MusE arranges your music in tracks and parts. The following +section shall provide you an overview of how things are done with MusE. +If you are or were a Cubase or Cakewalk user, you will feel familiar with +this. + +

+ +

+Tracks +

+There are two general classes of tracks: MIDI tracks and audio +tracks. MIDI tracks (and drum tracks which are internally MIDI tracks) +can hold note data. The Wave track is a type of audio track which holds +wave data. There are also several other kinds of audio tracks. + +

+ +

+MIDI tracks +

+MIDI and drum tracks hold MIDI event data. They don't differ much, +except that drum tracks offer a special editor which is more suitable +for drum editing. + +

+ +

+Wave tracks +

+They hold audio data which can be just played back or be piped through +effect plugin chains. They offer automation for these plugins. + +

+ +

+Audio input tracks +

+These provide the path for your audio data from outside into your +project. Set up the physical audio inputs you want to connect your +audio input track with, and then route the input tracks to various +other tracks such as wave tracks. + +

+ +

+Audio output tracks +

+These provide the path for your project's audio data to outside. Set +up the physical audio outputs you want to connect your audio out track +with, and then route various other tracks, such as wave tracks, to +the output tracks. + +

+ +

+Audio group tracks +

+Group tracks are like busses, where you can route other tracks to +them, then route the groups to other tracks. Since group tracks have +all the features of other audio tracks, like volume and pan, they +provide a convenient common routing point where you have control of +the sound before it is passed to other tracks. + +

+ +

+
+Audio aux tracks +

+These provide a more convenient way to mix several audio tracks +together. With each audio aux track added, other audio tracks will +gain a common send knob for adjusting the level sent to the aux +track. This can be more convenient than using several group tracks. + +

+ +

+Synthesizer tracks +

+This type of track is a software synthesizer which MIDI and drum tracks +can be assigned to. + +

+ +

+Creation +

+You can create a track by either right-clicking in the arranger's track list and then adding the desired track, or via the edit menu. + +

+ +

+Attributes +

+Tracks have several attributes: +
+
Mute:
+
If you click on the Mute field (denoted with +a "M" column header), the track gets muted and stops producing sound. +
+
Solo:
+
The solo button ("S" column +header) singles out a track for listening. It mutes +some other tracks but may phantom solo others. +For more info see the section on soloing: 2.5 and +phantom soloing: 2.5.1 +
+
Record:
+
The R column "arms" your track for recording. +When you rec-arm your song and have no tracks rec-armed, you won't be +able to record anything. See also the config option "move rec-arm with selection". +
+
Track name:
+
Double-click to edit the track name. +
+
Port:
+
For MIDI tracks, this lets you select the MIDI +port to which the events should be routed. This can be your physical +synthesizer or a software synthesizer. For soft synths, this is the +port the synth is associated to. For other track types, this is disabled. +
+
Channel:
+
For MIDI tracks, this is the MIDI channel the +output is sent to. For any kind of audio tracks, this is the number of +channels (mono, stereo). +
+
Automation:
+
For audio tracks, +this lets you set up the automation display in the arranger. +(See automation 2.7.1). Clicking this will provide you +with a popup menu with lots of submenus. Clicking on a submenu will +select or unselect it showing or hiding the automation parameter as a +graph overlaid on top of the track. +
+The submenus let you select the color you want to associate with the +automation parameter. There you can also assign midi controllers to +the parameters, a dialog is shown where you can manually choose the +midi controller, with a learn button to 'listen for' and +automatically recognize any midi controller operated by you. + +

+

+
Clef:
+
For MIDI tracks, you can specify a clef here. This +only affects the score editor. + +

+

+
+ +

+ +

+The trackinfo side bar +

+In the arranger and the part editors, you'll have a trackinfo sidebar +on the left side. You can set up track-type specific things there. + +

+ +

+
+MIDI trackinfo sidebar +

+The MIDI trackinfo sidebar lets you change program, volume, pan and +more. This sidebar can also be viewed at the left of the pianoroll +editor. + +
+Old style drum tracks: +
+These are MIDI tracks as well, but with a few differences. They allow +you to map certain drum sounds with different input notes, and you +can change the output settings of a certain "drum instrument" without +having to alter each single event. + +

+However, they have certain limitations: They only can handle 128 sounds +(even if you have more synthes), they aren't really compatible with +MIDI tracks (you can interchange parts between them, but if you touched +the drum list, you'll get unexpected results), you can't set a program +for the used channel and more. + +

+ +

+New style drum tracks +

+Because of these limitations, we introduced the new-style drum tracks. +They're not fully compatible with the old drum tracks, so the old are +still retained. Under "Global Settings", "GUI settings", you can set +up whether you prefer the old or new. + +

+They are handled exactly like plain MIDI tracks (staying compatible with +them), and offer all of the functionality, though in a different way. +They allow you to re-order the drum map efficiently, you can open parts +from multiple drum tracks in one drum editor (MusE will separate +the sounds from different tracks according to your settings, see the +"Window Config" menu), and you can set programs as with normal MIDI tracks. + +

+ +

+MIDI trackinfo controls: +
+
+
Output port:
+
This drop-down list selects the midi port +to send midi output from this track. +
+
Output channel:
+
This box selects the midi channel to be +used on the output port. +
+
Input and output routing:
+
Selects midi ports and +channels to receive midi from, and soloing paths. (See Routes +2.4). +
+
Midi through:
+
This button selects whether midi input is +passed through to the selected output port. +
+Depending on your midi devices and settings, there are cases when +this should be off such as using the same port and channel for +input and output (otherwise a double-note echo will be heard), +and cases when it must be on such as when using a synthesizer track +as output device. +
+
Input detect indicator:
+
Blinks when midi activity is +detected on the selected midi channels on the selected midi input +ports. +
+
Transpose:
+
This transposes midi input notes up or down +in pitch. This is very useful if your midi keyboard hasn't enough +keys or the selected output device plays an octave too low or high, +and you would like to shift the octave of the incoming notes to +compensate. +
+
Delay:
+
Adjusts the delay of the notes. +
+
Length:
+
Adjusts the length of the notes. +
+
Velocity:
+
Adjusts the velocity of incoming notes. +Use it to compensate for a too-loud or too-soft keyboard. +
+
Compression:
+
Adjusts the compression of incoming note +velocities. Use it to make soft incoming notes louder, and loud +notes not so loud. +
+
Instrument:
+
Selects the midi instrument patch to be used +by the selected output port. This is equivalent of dialing the patch +in the bank and program boxes, except it displays a more friendly +patch name as defined by the selected output port's midi +instrument. See instruments, or port configuration +2.8.1 +
+
H-Bank:
+
Selects the high bank number of the current patch. +
+
L-Bank:
+
Selects the low bank number of the current patch. +
+
Prog:
+
Selects the program number of the current patch. +
+
Volume:
+
Adjusts the midi volume controller. +
+
Pan:
+
Adjusts the midi pan controller. +
+
+The buttons beside the Prog, Volume, and Pan boxes store the value, +at the current transport position, for midi automation. (See +automation 2.7.1). + +

+Note that the 'Prog' button stores H-Bank and L-Bank along with +'Prog' value, so there are no H-Bank and L-Bank buttons. + +

+The 'All' button simply stores all three Program (and banks), Volume, +and Pan values at once. + +

+Tip: If the Song Type is GM, GS, or XG, you may need to store +desired values at transport position zero, otherwise your adjustments +may be overriden by the instrument when the transport is moved back +to position zero. If this behaviour is undesired, you can set the +Song Type to 'NO' meaning no song type. + +

+ +

+Audio trackinfo sidebar +

+Unlike the midi trackinfo sidebar, the audio trackinfo side bar +is nothing more than an embedded audio mixer strip, the exact same +strip as found in the mixers. (See mixer 2.2.2). + +
+Effects rack: +
+On the top of the audio trackinfo sidebar, there is an effects rack +which allows you to apply various plugins on the audio. For more +information on this, refer to 2.6.1. + +

+ +

+Parts +

+Within MIDI, drum and wave tracks, you can create parts. Parts +are chunks of coherent notes or wave data which can be moved around, +copied, cloned and deleted independent from other parts. + +

+Parts are created by selecting the pencil tool and then drawing onto +the right part area in the arranger. You can move them with the arrow +tool, delete them using the DEL key, and a right-click opens +a popup menu. This menu allows you even more stuff, such as setting +the part's color, saving the part to disk etc.. You can use +CTRL+C and CTRL+V for copying and pasting parts. +CTRL+B pastes the part as a clone. Pressing SHIFT +additionally provides you a dialog which allows you to paste the part +multiple times and set more stuff. + +

+You can also copy parts with the mouse by moving the part with the mouse +while holding down the CTRL key. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node7.html b/muse2/doc/html/split/documentation/node7.html new file mode 100644 index 00000000..5381fbcc --- /dev/null +++ b/muse2/doc/html/split/documentation/node7.html @@ -0,0 +1,169 @@ + + + + + +Routes + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+
+Routes +

+Routes are how tracks are connected together and to the outside world. +(They are also how Jack midi ports connect to the outside world. See +midi port configuration 2.8.1). +Each track strip has two buttons whose icons look like plugs. One button +is for input routing and the other is for output routing. Clicking on +these buttons will pop up a menu of available input or output routes that +you can connect to. Most audio tracks list other tracks to connect to, +but audio input and output tracks are special: Audio input track input +routing menus list available Jack audio input ports. Conversely audio +output track output routing menus list available Jack audio output ports. + +

+ +

+r0.25 +Image output_routing + +
+ +

+Meanwhile MIDI and drum tracks allow you to route available MIDI ports +and channels to the track using a handy popup matrix. + +

+ +

+r0.25 +Image midi_routing_matrix + +
+ +

+ +

+
+Anti circular routing +

+Any routing menu item which would cause a circular routing condition +is grayed out. Find out why the condition would exist by examining +routing paths involved and correct the situation if required. + +

+Also, you cannot use a track's aux sends if the track has an input +route path from ANY Aux Track. (See aux tracks 2.3.1). +Aux send knobs and labels are disabled in that case. + +

+ +

+
+Soloing chain routes +

+Soloing chains (see solo chains 2.5.2) are really just +routes like any other. The available solo chaining paths are displayed +in the routing popup menus. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node8.html b/muse2/doc/html/split/documentation/node8.html new file mode 100644 index 00000000..ad600c88 --- /dev/null +++ b/muse2/doc/html/split/documentation/node8.html @@ -0,0 +1,161 @@ + + + + + +Track soloing + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+
+Track soloing +

+Soloing allows you to single out a track for listening while muting others, +without you having to mute the other tracks. (See soloing track attribute +2.3.1). + +

+ +

+
+Phantom soloing +

+In order to solo a track and mute others so that it is heard, MusE +employs 'phantom' soloing: When a track is soloed, MusE automatically +solos all tracks routed to and from this track. (See routes +2.4). A phantom soloed track is indicated by a black square +in the track pane solo column. (See track attributes +2.3.1). + +

+ +

+ + + +
Figure 2.10: +Soloing, with phantom soloing
+
+ +
Image soloing_window
+
+ +

+ +

+
+Soloing chains +

+When an audio output track sends audio to some external entity, such +as an external running application, and audio from the external entity +is fed back into a MusE audio input track, solo chains allow you to +solo the input or output, and MusE will complete the path automatically +soloing the other, and all paths that came before or after it. + +

+Solo chains also work with MIDI tracks chained to audio inputs: +When a MIDI track drives some MIDI device whose audio is fed into MusE, +solo chains allow the entire chain to be soloed. + +

+Solo chains are accessed via routing menus. (See solo chain routes +2.4.2). + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/node9.html b/muse2/doc/html/split/documentation/node9.html new file mode 100644 index 00000000..53c1ca49 --- /dev/null +++ b/muse2/doc/html/split/documentation/node9.html @@ -0,0 +1,173 @@ + + + + + +Plugins + + + + + + + + + + + + + + + + + + + + + + +Subsections + + + +
+ +

+
+Plugins +

+Plugins are small add-ons which can process a track's data. + +

+MIDI plugins operate on midi and drum tracks, and are found in +the Midi menu. + +

+Audio plugins can be applied to any track handling audio (that is, +inputs, outputs, wave tracks, synth tracks). The effects rack +section describes this. (See effects rack 2.6.1). + +

+ +

+
+The audio effects rack +

+All audio track types (Input, Output, Group, Wave, Synth, and Aux) have +an effects rack into which audio plugins can be inserted in a chain. +Currently each rack can accomodate up to four plugins. + +

+MusE currently supports LADSPA plugins and DSSI synth and effects +plugins. + +

+Plugins can be added by double-clicking on an entry in the effect rack +in the track info pane (which is shown at the left side of the arranger +when the according track is selected). Right-clicking the rack items +offers a self-explanatory popup menu. + +

+All plugin controls can be automated. (See audio automation +2.7.1). + +

+One must carefully consider how many audio inputs and outputs a plugin +has, and how may channels the particular audio track has (1 mono or +2 stereo), and how MusE uses the plugins in the rack. + +

+Learn more about this in the appendix Understanding the Effects Rack: +3 + +

+ +

+ +
+Audio plugin Graphical User Interfaces (GUIs) +

Once a plugin is added, you need a way to +manipulate its controls, which affect its behaviour and operate +on the sound. + +

+MusE can show a generic GUI which contains all of the +plugin's controls arranged in a rather plain generic fashion. + +

+Some plugins may also have a native GUI which looks much better (it +was specifically designed for the plugin). + +

+Both GUI types are opened from the effects rack right-click popup menu. + +

+ +

+ + + + diff --git a/muse2/doc/html/split/documentation/output_routing.png b/muse2/doc/html/split/documentation/output_routing.png new file mode 100644 index 00000000..08af67fa Binary files /dev/null and b/muse2/doc/html/split/documentation/output_routing.png differ diff --git a/muse2/doc/html/split/documentation/project_my_first_song.png b/muse2/doc/html/split/documentation/project_my_first_song.png new file mode 100644 index 00000000..488faad2 Binary files /dev/null and b/muse2/doc/html/split/documentation/project_my_first_song.png differ diff --git a/muse2/doc/html/split/documentation/soloing_window.png b/muse2/doc/html/split/documentation/soloing_window.png new file mode 100644 index 00000000..72b72d63 Binary files /dev/null and b/muse2/doc/html/split/documentation/soloing_window.png differ diff --git a/muse2/doc/html/split/documentation/vam_synth.png b/muse2/doc/html/split/documentation/vam_synth.png new file mode 100644 index 00000000..f2e3bad4 Binary files /dev/null and b/muse2/doc/html/split/documentation/vam_synth.png differ -- cgit v1.2.3