1%% (c) 2012 florian jung 2%% (c) 2012 Robert Jonsson 3%% we should consider putting this under a proper license. GPL, or 4%% some GPL-like documentation license?? 5 6%% rules for editing documentation: (READ THIS FIRST) 7%% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 8%% 9%% please try to let newly written lines be shorter than 72 characters. 10%% minor exceptions are okay, but please not more than 80 chars. 11%% comments shall start after character #80 of the line (that is, 12%% they shall be "on the right margin") 13%% 14%% DON'T MIX up changes and reformatting in one commit. when changing 15%% stuff, please don't touch the lines before and after your change 16%% (that is, do not re-wrap them), even if it will look a bit patchy. 17%% this is for being able to easily use diff. 18%% when you want to reformat this file, then do it. but don't change 19%% anything, as this would be hard to find in a diff. and clearly 20%% state in the commit log that you "only" rearranged things. 21%% 22%% please adhere to the "User's manual" / "Internals" / "Design" 23%% partitioning (genereally, don't change the chapters until there 24%% is a really good reason for doing so (adding a chapter like 25%% "feature requests" as flo did in r1497 IS one). 26%% Below that, feel free to change the logical arrangement 27%% (making paragraphs to subsections and similar) if you deem it 28%% necessary. 29%% 30%% Whenever referring to code symbols, constants or source/header 31%% files, please use \sym{someClass::someSymbol}, \usym{UPPERCASE_THING} 32%% or \f{file.cpp}. 33%% Only specify file paths or namespaces where it would be ambiguous 34%% otherwise. Specify 'someClass::' until it would disturb the reader 35%% and it is obvious. you have to replace '_' by {\_} (with the {}!). 36%% These macros do automatic hyphenation on Camel-Case, under_-score 37%% and scope::-operator boundaries. If you need to insert additional 38%% hyphenation points, use {\-}. 39%% Example: \sym{someClass::someAb{\-}nor{\-}mal{\-}lyLongName} will 40%% hyphenate: some-Class::-some-Ab-nor-mal-ly-Long-Name 41%% 42%% Whenever referring to URLs, please wrap them in \url{blah}. Key 43%% combinations shall look like \key{CTRL+C}. Menu items shall look 44%% like \menu{Menu > Submenu > Menu Item}. 45%% 46%% Where possible, reference other parts of this documents with 47%% \label and \ref. Avoid duplicate information under "Internals" by 48%% referring to the appropriate section in "User's manual". 49%% 50%% Please do no time-stamping of sections. if you need time-stamps, 51%% use "svn blame documentation.tex" 52%% 53%% If you contribute something, feel free to add yourself to \author. 54%% 55%% If you don't speak LaTeX fluently, a few tips: 56%% * \section, \subsection, \subsubsection, \paragraph, \subparagraph 57%% let you create sections etc. just copy-and-paste if unsure. 58%% * you must prefix special characters like the underscore with \ 59%% (backslash) 60%% * \emph{some text} emphasizes the text, printing it italic. 61%% * \texttt{some text} displays the text in a typewriter font 62%% * \label{someName} creates a label at this position. this doesn't 63%% show up in the pdf. with \ref{someName}, you can reference to this 64%% label. (LaTeX will insert the section number instead of \ref) 65%% For this to work, you might need to recompile the .tex twice. 66%% 67%% 68%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 69%% 70%% Dependencies: 71%% To produce pdf output from this document the following packages are 72%% needed (atleast under Ubuntu derivatives) 73%% latex???-base 74%% texlive-latex-recommended 75%% texlive-latex-extra 76%% 77%% To produce a pdf version of this manual type: 78%% pdflatex documentation.tex <enter> 79%% A file documentation.pdf should be generated. 80%% 81%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 82 83 84 85\documentclass[a4paper]{report} 86\usepackage[a4paper, left=2.5cm, right=2.5cm, top=2.5cm, bottom=2.5cm]{geometry} 87\usepackage[T1]{fontenc} 88\usepackage[utf8]{inputenc} 89\usepackage{lmodern} 90\usepackage[english]{babel} 91\usepackage{graphicx} 92\usepackage{hyphenat} 93\usepackage{wrapfig} 94\usepackage{fancyhdr} 95\usepackage{hyperref} 96\usepackage{xcolor} 97\hypersetup{ 98 linkcolor=blue, 99 urlcolor=blue, 100 colorlinks=true, % hyperlinks will be blue 101 linkbordercolor=blue, % hyperlink borders will be blue 102 %pdfborderstyle={/S/U/W 1} % border style will be underline of width 1pt 103} 104\pagestyle{fancy} 105 \lhead{\scriptsize{\slshape\leftmark}} 106 \chead{} 107 \rhead{\thepage} 108 \lfoot{} 109 \cfoot{} 110 \rfoot{} 111 \renewcommand{\headrulewidth}{0.4pt} 112\usepackage{ifthen} 113 114% Hyphenate symbols before each uppercase letter, after each underscore 115% (without a "-") and after each ':' (without a "-") 116% TODO for any latex crack: also do automatic hyphenation, that is, 117% instead of some-Automation-Expression, do some-Au-to-ma-tion-Ex-press-ion 118\makeatletter 119\newcommand{\camelhyph}[1]{\@fterfirst\c@amelhyph#1\relax } 120\newcommand{\underscorehyph}[1]{\@fterfirst\u@nderscorehyph#1\relax } 121\def\@fterfirst #1#2{#2#1} 122\def\c@amelhyph #1{% 123\ifthenelse{\equal{#1}\relax}{}{% Do nothing if the end has been reached 124 \ifnum`#1=95 \_\hspace{0pt}\else % Check whether #1 is "_", then print _[thin space] 125 \ifnum`#1=58 :\hspace{0pt}\else 126 \ifnum`#1>64 127 \ifnum`#1<91 \-#1\else#1\fi% Check whether #1 is an uppercase letter, 128 \else#1\fi 129 \fi 130 \fi 131 % if so, print \-#1, otherwise #1 132 \expandafter\c@amelhyph% % insert \c@amelhyph again. 133}} 134\def\u@nderscorehyph #1{% 135\ifthenelse{\equal{#1}\relax}{}{% Do nothing if the end has been reached 136 \ifnum`#1=95 \_\hspace{0pt}\else % Check whether #1 is "_", then print _\- 137 \ifnum`#1=58 :\hspace{0pt}\else#1\fi\fi 138 \expandafter\u@nderscorehyph% % insert \u@nderscorehyph again. 139}} 140\makeatother 141 142 143 144\author{Florian Jung, Robert Jonsson, Tim Donnelly} 145\title{MusE Documentation} 146 147% Orcan: not needed since the hyperref package takes care of all 148%\newcommand{\url}[1]{\texttt{#1}} 149\newcommand{\key}[1]{\textbf{#1}} 150\newcommand{\shell}[1]{\texttt{\textbf{#1}}} 151\newcommand{\menu}[1]{\textbf{#1}} 152\newcommand{\sym}[1]{\texttt{\camelhyph{#1}}} 153\newcommand{\listing}[1]{\texttt{\camelhyph{#1}}} 154\newcommand{\usym}[1]{\texttt{\underscorehyph{#1}}} 155\newcommand{\file}[1]{\texttt{\camelhyph{#1}}} 156\newcommand{\screenshotwidth}[0]{0.8\textwidth} 157 158 159\begin{document} 160\begin{figure}[htp] 161\centering \includegraphics[width=1.0\textwidth]{pics/muse2} 162\label{fig:MusE} 163\end{figure} 164\tableofcontents 165\chapter{What is this?} 166You are, if you have printed this document, holding in your hand the 167written documentation for the audio and midi sequencer MusE version 2.\\ 168\url{http://www.muse-sequencer.org} is MusE's home on the internet where 169everything MusE related should be possible to find, software, this 170documentation, forums, mailing lists, bug reporting, FAQs. If you have 171this document but not the software head on over there to find what it's 172all about. 173\chapter{User's manual} 174 175\section{Introduction} 176\subsection{A brief history of computer audio and MusE} 177To quickly summarize over a decades open source development: in 1999 Werner 178 Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first 179few releases (actually not few, Werner relentlessly churned out new releases) 180MusE was only a midi sequencer. The target was to create a fully fledged 181midi sequencer for the Linux operating system. Over the years audio was 182added among with other things implemented and sometimes abandoned. 183Today MusE is a stable and feature rich music creation environment which 184strives to encompass most of the music recording process, creation, editing, 185mastering. 186 187\subsection{Definitions} 188\key{CTRL} refers to the control key on the keyboard, e.g. \key{CTRL+C} 189means to press and hold the control key while pressing the c key. Make sure 190you know where you have it so you won't accidentally lose control 191(bad jokes are the best jokes, so say we all!).\\ 192\key{SHIFT} refers to the shift key on the keyboard, see above for usage\\ 193\key{ALT} refers to the alt key on the keyboard, see above for usage\\ 194\shell{\$>} is used as a generic definition for a terminal prompt. When the 195manual lists a command that shall be typed, the prompt is not part of the 196command.\\ 197Keys are always referred to in bold uppercase, e.g. \key{A}. For instance 198\key{SHIFT+A} for the key a pressed together with the shift key.\\ 199Sometimes terminal examples are written tabbed in with a fixed font to 200visualize more closely what something looks like on the screen. 201E.g.\\ 202\hspace*{1cm}\shell{\$> muse2}\\ 203 204\subsection{Getting up and running for impatient people} 205Install MusE from the repository of your chosen distribution. 206To get decent performance start \href{http://jackaudio.org/}{Jack} with 207the following command in a terminal:\\ 208\hspace*{1cm}\shell{\$> jackd -d alsa -d hw:0 -p 256}\\ 209Or, if you prefer, use the launcher utility 210\href{http://qjackctl.sourceforge.net/}{QJackCtl} to get some 211help starting Jack. 212After this, start MusE from the menu or fire up another terminal and 213type 214 215\shell{muse2}.\\ 216If this didn't work out read on for the slightly more complete route for 217getting things started. 218 219\subsection{Getting up and running} 220\subsubsection{Installation from binaries} 221There are several ways to install MusE depending on your situation. The 222most convenient way is to install a prepackaged version from your chosen 223distribution. The drawback of this is that it may not be the most recent 224version, though often there is a more recent package from a private packager. 225\subsubsection{Installation from source} 226Building MusE from source is not hard, there are a number of prerequistes 227that must be met but the actual building should be painless (ha, famous 228last words).\\ 229Please follow the README in the source package and/or read the instructions 230on the homepage: \url{http://muse-sequencer.org/index.php/Installation} 231 232\subsubsection{Hardware} 233MusE on the Linux platform supports midi through ALSA and Jack-midi and audio 234through Jack. For information on what hardware is supported there are some 235convenient places to check: 236\begin{itemize} 237\item Alsa soundcard matrix at 238\url{http://www.alsa-project.org/main/index.php/Matrix:Main} 239\item \url{http://FFADO.org} for firewire devices. 240\end{itemize} 241Also, as is often a very good approach for Linux and open source, the 242various forums available on the internet often contain good information. 243Chances are someone has already tried your configuration and/or had your 244specific problem and the solution is already written down. 245\subsubsection{Launching} 246After installation the binary muse2 is installed on the computer. If MusE 247was installed from a distribution repository the binary may have a 248different name depending on the distribution policies. Most distributions 249do however install a menu entry so MusE should be conveniently available 250from there. 251\subsubsection{Audio preconditions} 252In the standard case MusE expects to find and connect to the Jack audio 253server \url{http://jackaudio.org}. Make sure jack is installed (if MusE was 254installed with a distribution-package Jack will very likely already be 255installed) For Jack to run with best performance your system should be 256sufficiently tuned to allow it to run with realtime capabilities. The 257realtime configuration is configuration of the operating system and roughly 258consists of two parts. 259\begin{enumerate} 260\item By default on most distros only the superuser lets applications setup 261realtime capabilities. Please see the APPENDIX for setting up realtime 262\item Maximizing performance. A standard linux installation may not able 263to reach the performance required by a power user. This requires exchanging 264the linux kernel for a so called lowlatency kernel, this is also covered by 265the realtime APPENDIX. 266\end{enumerate} 267 268\subsubsection{Running MusE} 269Find MusE in the menu or open a terminal and enter muse2. 270 271\shell{\$> muse2}\\A splash screen should pop up followed 272by the main application window and you are off!\\ 273If an error like the screenshot below pops up the Jack audio server is 274either not running or started as a different user than what you are trying 275to start MusE as. 276\begin{figure}[htp] 277\centering \includegraphics[width=\screenshotwidth]{pics/no_audio} 278\caption{Jack server missing} 279\label{fig:no_audio} 280\end{figure} 281\subsubsection{Midi only} 282MusE can be started in Midi-only mode where MusE does not have any external 283dependencies apart from ALSA midi. In this case start MusE from a terminal: 284\shell{\$> muse2 -a} 285 286\subsubsection{ALSA midi with Jack} 287If Jack is running, by default MusE will not use ALSA devices, preferring 288Jack midi instead. To force ALSA devices to be used as well as Jack 289midi, start MusE with the -A option: \shell{\$> muse2 -A} 290 291\subsection{Beginners tutorial} 292To get a quick grip of what MusE can achieve please follow this beginners 293tutorial. 294\subsubsection{Midi Setup} 295First off, fire up MusE as was described in the previous chapter, making 296sure that the jack audio server is started with sufficient configuration 297to allow for audio output without breakup. Also make sure your system can 298make sound. 299\subsubsection{Soft synth test} 300With MusE up and running right click in the Track-pane (see 301Fig. \ref{fig:Main Window}) and select 302\menu{Add Synth > MESS > vam soft synth}. 303A Soft Synth track called vam-0 should appear as well as a separate GUI 304for the synthesizer. 305 306Now right click once more in the Track-pane and select \menu{Add Midi 307Track}. Another track appears called Track 1, and its track list Port 308column should show it is bound to the synth that was just created vam-0. 309If it is not, click on the Track 1 Port column to open a drop-down list 310of available devices and choose vam-0. 311 312\begin{wrapfigure}{r}{0.05\textwidth} 313\includegraphics[width=0.05\textwidth]{pics/arrow_tool} 314%\hrulefill 315\end{wrapfigure} 316Now select the drawing tool icon 317from the toolbar, alternatively press the shortcut key \key{D}. 318Move the mouse over to the arranger canvas as referenced in 319Fig. \ref{fig:Main Window} 320and point at the midi track, the mouse should have changed to a small pencil. 321Draw a Part along the midi track using the mouse. For this exercise it is 322not important where or how large the drawn Part is. When you are done double 323click on the drawn part. This will open up the Piano Roll editor. To the 324left of the Piano Roll there are piano keys in a vertical line, try clicking 325on the keys in this virtual keyboard each click should be rewarded with a 326synth sound (maybe of questionable quality, a sound nevertheless) 327\begin{figure}[htp] 328\centering \includegraphics[width=.5\textwidth]{pics/vam_synth} 329\caption{vam synthesizer} 330\label{fig:vam_synth} 331\end{figure} 332 333\subsubsection{Missing sound} 334If you got sound from the previous exercise you can carry on to the next, 335or keep reading for further enlightenment in case you come upon trouble 336later on. If there is no sound we need to do some fault hunting. First 337off, click on Arranger window once more and select the vam-0 track in the 338track-pane. 339\begin{figure}[htp] 340\centering \includegraphics[width=\screenshotwidth] 341{pics/main_window_with_midi_editor_vam} 342\caption{Midi editor view} 343\label{fig:Midi editor} 344\end{figure} 345Now bring back Piano Roll window and align the windows so you 346can see the piano keys as well as the Meter on the Mixer Strip (see the 3475 Function by function chapter for more information on these windows). 348The result should be something like the following: 349 350When pressing one of the keys on virtual Keyboard the Meter on the Mixer 351Strip should light up in green to visualize that the Synth is making 352sound, if it is not try to trace back your steps and and see if you did 353anything differently than described. 354Now, if the Meter lights up but there is still no sound we need to 355check the routing between the tracks. Click on the Arranger window again 356and select the Out 1 track, this is the predefined output which MusE by 357default loads at startup, at the bottom of Mixer Strip there are two 358buttons looking like tele- jacks, these bring up the inputs and outputs 359of the track, click on the right one, the output and make sure that it is 360connected to some valid outputs on your system. 361\begin{wrapfigure}{r}{0.25\textwidth} 362\includegraphics[width=0.25\textwidth]{pics/output_routing} 363%\hrulefill 364\end{wrapfigure} 365Click on the outputs to select them, if you did changes here go back and 366try clicking on the Piano Roll keyboard again, hopefully it helped. If there 367still are problems make sure your system actually can make sound through 368Jack, this is however getting outside the scope of this manual.\\\\ 369\textit{This might be the time to bring up the concept of community support. 370Open source software could never be what it is without the support given by 371individuals on forums and mailinglists, if the information given in this 372document is not enough, try googling your problem and/or get in touch with 373one of the online forums for MusE or Linux audio in general. See some pointers 374in the Support chapter.} 375 376 377\subsubsection{Recording Midi} %TODO: walkthrough of recording midi 378TBD 379\subsubsection{Recording Audio} 380At this point we'll make a slight detour into full on audio recording. Getting 381audio out of MusE has already been covered in the previous chapters so we will 382concentrate on the additional steps needed to record onto an audio track.\\ 383\\ 384When MusE is first fired up, the 385output track has already been created (more about this in the chapter about 386templates), to proceed with audio recording we need to add two additional tracks, a 387wave track and an input track.\\ 388When MusE is first started right click in an empty space on the track view 389\begin{figure}[htp] 390\centering \includegraphics[width=\screenshotwidth] 391{pics/main_window_add_track} 392\caption{Add track} 393\label{fig:Add track} 394\end{figure} 395and select \menu{Add Audio Input}. Right click again and also select 396\menu{Add Wave Track}. Two additional tracks are now visible in the Arranger, 397"Input 1" and "Track 1", bring up the mixer with \menu{F10} and you should see 398the following configuration. 399\begin{figure}[htp] 400\centering \includegraphics[width=0.25\textwidth]{pics/mixer_with_one_input} 401\caption{Mixer with one input} 402\label{fig:Mixer with one input} 403\end{figure} 404\\ 405Note the buttons on each mixer strip. hover over them to see their 406functionality. For more information on all the buttons see coming chapters 407about the mixer. For now lets just do what we must.\\ 4081. click on the stereo symbol over the slider to change the input to a mono track.\\ 4092. do the same for the wave track (optional)\\ 4103. click on the Mute (gray speaker) icon on the input track to unmute it.\\ 4114. click on the input routing button (see the tooltip, it looks like a tele plug) 412on the input track and select an appropriate connection from your system.\\ 4135. click on the output routing button on the input track and select 414\textbf{Track 1}\\ 415\\ 416Already after the meter on the input track should be able to display that there 417is incoming sound from your sound source. If there actually is sound coming 418from your sound source, that is.\\ 419We are now nearly ready to start recording. First we need to select a location 420to store the files. MusE does not use a centralized storage of soundfiles but 421uses the path of the song-file (extension .med) as guidance as to where the 422audio files should be placed. Now as it happens MusE will prohibit us from 423starting a recording until the songfile has been stored. So lets take advantage 424of this behaviour and just go ahead and try to record. Let's get started.\\ 425In the mixer click on the red \textbf{record} dot on the Audio Track to arm it 426for recording (or enable if you will). Now when there is audio coming into the 427input it will also show up on the Audio Track. Also note that all the input and 428output routing buttons on the tracks now have the same gray color, this means 429that all of the tracks have a proper connection. 430\begin{figure}[htp] 431\centering \includegraphics[width=0.25\textwidth]{pics/mixer_with_one_input_buttons} 432\caption{Mixer buttons} 433\label{fig:Mixer buttons} 434\end{figure} 435\\ 436All fine and dandy. Now bring up the arranger window and find the round, red on 437white \textbf{record} button and click on it. This is your queue to MusE to 438prepare for recording. However since we have not saved our song we are presented 439with a dialog to do just that.\\ 440\begin{figure}[htp] 441\centering \includegraphics[width=0.6\textwidth]{pics/project_my_first_song} 442\caption{Save song} 443\label{fig:Save song} 444\end{figure} 445Note the check box for creating a project folder, when working with audio this 446is very much recommended or you may soon loose track of what audio files belong 447to which song.\\ 448Finally we are ready to start recording! The process is completed by clicking 449on the \textbf{Play} button in the Arranger. If all went well MusE then starts 450to record a wave file from the Input Track placed in your song directory.\\ 451When you wish to stop recording press \textbf{Stop} in the Arranger, now the 452resulting waveform should be visible in the Arranger. After rewinding the Play 453position and pressing \textbf{Play} again the resulting sound should be audible 454through the connected output. 455 456 457\section{Basic overview} 458In this section we will make a step by step walk-through of all the 459different editors, their purpose and what functions they support. 460 461\subsection{Main/Arranger} 462 463\label{Main/Arranger} 464\begin{figure}[htp] 465\centering \includegraphics[width=\screenshotwidth] 466{pics/main_window_annotated} 467\caption{MusE main window} 468\label{fig:Main Window} 469\end{figure} 470Above is the main window of MusE, the Arranger, this is what greets you 471when launching MusE. The Arranger consists of two main parts, the Track-pane 472and the Arranger canvas. The Track-pane lists all currently visible tracks 473and the Arranger canvas contains all Parts of the composition. The 474screenshot above shows an empty project. Below is MusE with a song in 475progress, turns out it wasn't a very good song, but for our purposes it 476is fine. In the below screenshot there are a lot of tracks visible in the 477Track-pane, each have an icon which indicate it's type, wave-track, input, 478output etcetera, more about that later. In the Arranger canvas a number of 479parts are visible, the ones in yellow are in this composition wave files, 480the multicolored line are different Parts of a drum track. 481 482\begin{figure}[htp] 483\centering \includegraphics[width=\screenshotwidth] 484{pics/main_window_with_arrangement} 485\caption{MusE main window with arrangement} 486\label{fig:Main Window with arrangement} 487\end{figure} 488 489\subsection{Mixer} \label{mixer} 490Choosing \menu{View > Mixer A} or \menu{B} from the menu in the main 491window will bring up the mixer as viewed below. The mixer will open with 492all options enabled, showing channel strips for all tracks in the current 493setup, depending on how far you have gotten this view may become very large, 494at which point it may be a good idea to limit what is viewed in the Mixer. 495From the view menu all the different kinds of tracks can be toggled on/off 496from the mixer. Some may find it a good idea to use the two mixers A and B 497setup with different setup and store this in your song template(s), more 498about this in the Song Template section. It can be argued that everything 499in MusE is a track analogous to the Unix idiom that everything is a file. 500The types of tracks visible in the mixer (and track-pane) are: 501\begin{wrapfigure}{r}{0.5\textwidth} 502\includegraphics[width=0.5\textwidth]{pics/mixer} 503%\hrulefill 504\end{wrapfigure} 505\begin{itemize} 506\item Audio output 507\item Audio input 508\item Group track 509\item Aux track 510\item Wave track 511\item Synth track 512\item Midi track 513\end{itemize} 514 515 516There is also a Midi Track variation called Drum Track, they are 517however not distinguishable from Midi Tracks in the Mixer. Also the 518strips for midi tracks are different in the Mixer than in the 519Track-pane view. 520 521\section{Tracks and parts} 522MusE arranges your music in \emph{tracks} and \emph{parts}. The following 523section shall provide you an overview of how things are done with MusE. 524If you are or were a Cubase or Cakewalk user, you will feel familiar with 525this. 526 527\subsection{Tracks} 528There are two general classes of tracks: MIDI tracks and audio 529tracks. MIDI tracks (and drum tracks which are internally MIDI tracks) 530can hold note data. The Wave track is a type of audio track which holds 531wave data. There are also several other kinds of audio tracks. 532 533\paragraph{MIDI tracks} 534MIDI and drum tracks hold MIDI event data. They don't differ much, 535except that drum tracks offer a special editor which is more suitable 536for drum editing. 537 538\paragraph{Wave tracks} 539They hold audio data which can be just played back or be piped through 540effect plugin chains. They offer automation for these plugins. 541 542\paragraph{Audio input tracks} 543These provide the path for your audio data from outside into your 544project. Set up the physical audio inputs you want to connect your 545audio input track with, and then route the input tracks to various 546other tracks such as wave tracks. 547 548\paragraph{Audio output tracks} 549These provide the path for your project's audio data to outside. Set 550up the physical audio outputs you want to connect your audio out track 551with, and then route various other tracks, such as wave tracks, to 552the output tracks. 553 554\paragraph{Audio group tracks} 555Group tracks are like busses, where you can route other tracks to 556them, then route the groups to other tracks. Since group tracks have 557all the features of other audio tracks, like volume and pan, they 558provide a convenient common routing point where you have control of 559the sound before it is passed to other tracks. 560 561\paragraph{Audio aux tracks} \label{aux_tracks} 562These provide a more convenient way to mix several audio tracks 563together. With each audio aux track added, other audio tracks will 564gain a common send knob for adjusting the level sent to the aux 565track. This can be more convenient than using several group tracks. 566 567\paragraph{Synthesizer tracks} 568This type of track is a software synthesizer which MIDI and drum tracks 569can be assigned to. 570 571\paragraph{Creation} 572You can create a track by either right-clicking in the arranger's track % TODO: insert screenshot 573list and then adding the desired track, or via the edit menu. 574 575\paragraph{Attributes} 576Tracks have several attributes: 577\begin{description} 578\item [{Mute:}] If you click on the \emph{Mute} field (denoted with 579a "M" column header), the track gets muted and stops producing sound. 580\item [{Solo:}] \label{track_attr_solo} The solo button ("S" column 581header) singles out a track for listening. It mutes 582some other tracks but may phantom solo others. 583For more info see the section on soloing: \ref{track_soloing} and 584phantom soloing: \ref{phantom_soloing} 585\item [{Record:}] The R column "arms" your track for recording. 586When you rec-arm your song and have no tracks rec-armed, you won't be 587able to record anything. See also the config option "move rec-arm with % TODO: reference to rec-arm config option 588selection". 589\item [{Track name:}] Double-click to edit the track name. 590\item [{Port:}] For MIDI tracks, this lets you select the MIDI 591port to which the events should be routed. This can be your physical 592synthesizer or a software synthesizer. For soft synths, this is the 593port the synth is associated to. For other track types, this is disabled. 594\item [{Channel:}] For MIDI tracks, this is the MIDI channel the 595output is sent to. For any kind of audio tracks, this is the number of 596channels (mono, stereo). 597 % TODO: what's that "T" column?! 598\item [{Automation:}] \label{track_attr_automation} For audio tracks, 599this lets you set up the automation display in the arranger. 600(See automation \ref{audio_automation}). Clicking this will provide you 601with a popup menu with lots of submenus. Clicking on a submenu will 602select or unselect it showing or hiding the automation parameter as a 603graph overlaid on top of the track.\\ 604The submenus let you select the color you want to associate with the 605automation parameter. There you can also assign midi controllers to 606the parameters, a dialog is shown where you can manually choose the 607midi controller, with a \emph{learn} button to 'listen for' and 608automatically recognize any midi controller operated by you. 609 610\item [{Clef:}] For MIDI tracks, you can specify a clef here. This 611only affects the score editor. 612 613\end{description} 614 615\subsubsection{The trackinfo side bar} 616In the arranger and the part editors, you'll have a trackinfo sidebar 617on the left side. You can set up track-type specific things there. 618 619\paragraph{MIDI trackinfo sidebar} \label{midi_trackinfo_sidebar} 620The MIDI trackinfo sidebar lets you change program, volume, pan and 621more. This sidebar can also be viewed at the left of the pianoroll 622editor. %%FIXME Ref to pianoroll 623\subparagraph{Old style drum tracks:} 624These are MIDI tracks as well, but with a few differences. They allow 625you to map certain drum sounds with different input notes, and you 626can change the output settings of a certain "drum instrument" without 627having to alter each single event. 628 629However, they have certain limitations: They only can handle 128 sounds 630(even if you have more synthes), they aren't really compatible with 631MIDI tracks (you can interchange parts between them, but if you touched 632the drum list, you'll get unexpected results), you can't set a program 633for the used channel and more. 634 635\subsubsection{New style drum tracks} 636Because of these limitations, we introduced the new-style drum tracks. 637They're not fully compatible with the old drum tracks, so the old are 638still retained. Under "Global Settings", "GUI settings", you can set 639up whether you prefer the old or new. 640 641They are handled exactly like plain MIDI tracks (staying compatible with 642them), and offer all of the functionality, though in a different way. 643They allow you to re-order the drum map efficiently, you can open parts 644from multiple drum tracks in \emph{one} drum editor (MusE will separate 645the sounds from different tracks according to your settings, see the 646"Window Config" menu), and you can set programs as with normal MIDI tracks. 647 648\subparagraph{MIDI trackinfo controls:} 649\begin{description} 650\item [{Output port:}] This drop-down list selects the midi port 651to send midi output from this track. 652\item [{Output channel:}] This box selects the midi channel to be 653used on the output port. 654\item [{Input and output routing:}] Selects midi ports and 655channels to receive midi from, and soloing paths. (See Routes 656\ref{routes}). 657\item [{Midi through:}] This button selects whether midi input is 658passed through to the selected output port.\\ 659Depending on your midi devices and settings, there are cases when 660this should be off such as using the same port and channel for 661input and output (otherwise a double-note \emph{echo} will be heard), 662and cases when it must be on such as when using a synthesizer track 663as output device. 664\item [{Input detect indicator:}] Blinks when midi activity is 665detected on the selected midi channels on the selected midi input 666ports. 667\item [{Transpose:}] This transposes midi input notes up or down 668in pitch. This is very useful if your midi keyboard hasn't enough 669keys or the selected output device plays an octave too low or high, 670and you would like to shift the octave of the incoming notes to 671compensate. 672\item [{Delay:}] Adjusts the delay of the notes. %% FIXME What is this again? Does it work? 673\item [{Length:}] Adjusts the length of the notes. %% FIXME What is this again? Does it work? 674\item [{Velocity:}] Adjusts the velocity of incoming notes. 675Use it to compensate for a too-loud or too-soft keyboard. 676\item [{Compression:}] Adjusts the compression of incoming note 677velocities. Use it to make soft incoming notes louder, and loud 678notes not so loud. 679\item [{Instrument:}] Selects the midi instrument patch to be used 680by the selected output port. This is equivalent of dialing the patch 681in the bank and program boxes, except it displays a more friendly 682patch \emph{name} as defined by the selected output port's midi 683instrument. See instruments, or port configuration %% FIXME Ref to instruments. 684\ref{midi_port_config} 685\item [{H-Bank:}] Selects the high bank number of the current patch. 686\item [{L-Bank:}] Selects the low bank number of the current patch. 687\item [{Prog:}] Selects the program number of the current patch. 688\item [{Volume:}] Adjusts the midi volume controller. 689\item [{Pan:}] Adjusts the midi pan controller. 690\end{description} 691The buttons beside the Prog, Volume, and Pan boxes store the value, 692at the current transport position, for midi automation. (See 693automation \ref{midi_automation}). 694 695Note that the 'Prog' button stores H-Bank and L-Bank along with 696'Prog' value, so there are no H-Bank and L-Bank buttons. 697 698The 'All' button simply stores all three Program (and banks), Volume, 699and Pan values at once. 700 701\emph{Tip:} If the Song Type is GM, GS, or XG, you may need to store %% FIXME Ref to song type 702desired values at transport position zero, otherwise your adjustments 703may be overridden by the instrument when the transport is moved back 704to position zero. If this behaviour is undesired, you can set the 705Song Type to 'NO' meaning no song type. %% FIXME Ref to explanation of instruments and default controller values 706 707\paragraph{Audio trackinfo sidebar} 708Unlike the midi trackinfo sidebar, the audio trackinfo side bar 709is nothing more than an embedded audio mixer strip, the exact same 710strip as found in the mixers. (See mixer \ref{mixer}). 711\subparagraph{Effects rack:} 712On the top of the audio trackinfo sidebar, there is an effects rack 713which allows you to apply various plugins on the audio. For more 714information on this, refer to \ref{effects_rack}. 715 716 717\subsection{Parts} 718Within MIDI, drum and wave tracks, you can create \emph{parts}. Parts 719are chunks of coherent notes or wave data which can be moved around, 720copied, cloned and deleted independent from other parts. 721 722Parts are created by selecting the pencil tool and then drawing onto 723the right part area in the arranger. You can move them with the arrow 724tool, delete them using the \key{DEL} key, and a right-click opens 725a popup menu. This menu allows you even more stuff, such as setting 726the part's color, saving the part to disk etc.. You can use 727\key{CTRL+C} and \key{CTRL+V} for copying and pasting parts. 728\key{CTRL+B} pastes the part as a clone. Pressing \key{SHIFT} 729additionally provides you a dialog which allows you to paste the part 730multiple times and set more stuff. 731 732You can also copy parts with the mouse by moving the part with the mouse 733while holding down the \key{CTRL} key. 734 735 736\section{Routes} \label{routes} 737Routes are how tracks are connected together and to the outside world. 738(They are also how Jack midi ports connect to the outside world. See 739midi port configuration \ref{midi_port_config}). 740Each track strip has two buttons whose icons look like plugs. One button 741is for input routing and the other is for output routing. Clicking on 742these buttons will pop up a menu of available input or output routes that 743you can connect to. Most audio tracks list other tracks to connect to, 744but audio input and output tracks are special: Audio input track input 745routing menus list available Jack audio input ports. Conversely audio 746output track output routing menus list available Jack audio output ports. 747 748\begin{wrapfigure}{r}{0.25\textwidth} 749\includegraphics[width=0.25\textwidth]{pics/output_routing} 750%\hrulefill 751\end{wrapfigure} 752 753Meanwhile MIDI and drum tracks allow you to route available MIDI ports 754and channels to the track using a handy popup matrix. 755 756\begin{wrapfigure}{r}{0.25\textwidth} 757\includegraphics[width=0.25\textwidth]{pics/midi_routing_matrix} 758%\hrulefill 759\end{wrapfigure} 760 761 762\subsection{Anti circular routing} \label{anti_circular_routing} 763Any routing menu item which would cause a circular routing condition 764is grayed out. Find out why the condition would exist by examining 765routing paths involved and correct the situation if required. 766 767Also, you cannot use a track's aux sends if the track has an input 768route path from ANY Aux Track. (See aux tracks \ref{aux_tracks}). 769Aux send knobs and labels are disabled in that case. 770 771\subsection{Soloing chain routes} \label{soloing_chain_routes} 772Soloing chains (see solo chains \ref{soloing_chains}) are really just 773routes like any other. The available solo chaining paths are displayed 774in the routing popup menus. 775 776\section{Track soloing} \label{track_soloing} 777Soloing allows you to single out a track for listening while muting others, 778without you having to mute the other tracks. (See soloing track attribute 779\ref{track_attr_solo}). 780 781\subsection{Phantom soloing} \label{phantom_soloing} 782In order to solo a track and mute others so that it is heard, MusE 783employs 'phantom' soloing: When a track is soloed, MusE automatically 784solos all tracks routed to and from this track. (See routes 785\ref{routes}). A phantom soloed track is indicated by a black square 786in the track pane solo column. (See track attributes 787\ref{track_attr_solo}). 788 789 790\begin{figure}[htp] 791\centering \includegraphics[width=\screenshotwidth]{pics/soloing_window} 792\caption{Soloing, with phantom soloing} 793\label{fig:Soloing} 794\end{figure} 795 796\subsection{Soloing chains} \label{soloing_chains} 797When an audio output track sends audio to some external entity, such 798as an external running application, and audio from the external entity 799is fed back into a MusE audio input track, solo chains allow you to 800solo the input or output, and MusE will complete the path automatically 801soloing the other, and all paths that came before or after it. 802 803Solo chains also work with MIDI tracks chained to audio inputs: 804When a MIDI track drives some MIDI device whose audio is fed into MusE, 805solo chains allow the entire chain to be soloed. 806 807Solo chains are accessed via routing menus. (See solo chain routes 808\ref{soloing_chain_routes}). 809 810\section{Plugins} \label{plugins} 811Plugins are small add-ons which can process a track's data. 812 813MIDI plugins operate on midi and drum tracks, and are found in 814the \menu{Midi} menu. 815 816Audio plugins can be applied to any track handling audio (that is, 817inputs, outputs, wave tracks, synth tracks). The effects rack 818section describes this. (See effects rack \ref{effects_rack}). 819 820\subsection{The audio effects rack} \label{effects_rack} 821All audio track types (Input, Output, Group, Wave, Synth, and Aux) have 822an effects rack into which audio plugins can be inserted in a chain. 823Currently each rack can accommodate up to four plugins. 824 825MusE currently supports LADSPA plugins and DSSI synth and effects 826plugins. 827 828Plugins can be added by double-clicking on an entry in the effect rack 829in the track info pane (which is shown at the left side of the arranger 830when the according track is selected). Right-clicking the rack items 831offers a self-explanatory popup menu. 832 833All plugin controls can be automated. (See audio automation 834\ref{audio_automation}). 835 836One must carefully consider how many audio inputs and outputs a plugin 837has, and how may channels the particular audio track has (1 mono or 8382 stereo), and how MusE uses the plugins in the rack. 839 840Learn more about this in the appendix Understanding the Effects Rack: 841\ref{apx_effects_rack} 842 843\subsubsection{Audio plugin Graphical User Interfaces (GUIs)} 844\label{plugin_guis} Once a plugin is added, you need a way to 845manipulate its controls, which affect its behaviour and operate 846on the sound. 847 848MusE can show a generic GUI which contains all of the 849plugin's controls arranged in a rather plain generic fashion. 850 851Some plugins may also have a native GUI which looks much better (it 852was specifically designed for the plugin). 853 854Both GUI types are opened from the effects rack right-click popup menu. 855 856\section{Automation} \label{automation} 857Automation is the ability to record (or construct) and playback 858exact sequences of control movements. 859 860MIDI and audio automation are each currently uniquely different, 861but share some similarities. 862 863\subsection{Audio automation} \label{audio_automation} 864Almost all graphical audio controls in MusE can be automated. 865 866This includes an audio track's volume and pan, and the controls 867of any plugins in the effects rack, and if the track is a 868synthesizer track, all of the synth's controls. 869 870Each control has a manual adjustment value. This value is shown 871when there is no automation data at all, or automation has been 872disabled. 873 874For plugin and synth controls, it is usually more desirable to 875manipulate automation with the generic plugin GUIs, because 876MusE has full control over their behaviour. (See plugin GUIs 877\ref{plugin_guis}). 878 879There are a few ways to enter audio automation data: 880\begin{itemize} 881\item By adjusting audio controls while the transport is rolling. 882MusE will record the exact movements. 883\item By adjusting audio controls while the transport is stopped, 884at different transport positions. TOUCH mode allows this. 885\item By right-clicking any audio control and choosing an operation 886from the automation popup menu. This includes storing, erasing, 887and clearing automation events, and seeking the next or previous 888event. 889\item By drawing the data on the audio track's automation graphs. 890(See track automation \ref{track_attr_automation}). 891\end{itemize} 892\paragraph{Audio automation modes} 893Each audio track strip has an automation mode button 894at the bottom. There are four automation modes: 895\begin{description} 896\item [{OFF:}] Disables all automation, uses manual value always. 897\item [{READ:}] Automation data is applied to controls. If any 898automation data exists, the manual value is overridden and has 899no effect. 900\item [{TOUCH:}] Allows you to alter a control at any time, while 901transport is stopped or rolling, If rolling, when the control is 902released it returns to reading from automation data. 903\item [{WRITE:}] Allows to adjust an initial value before rolling 904the transport. While rolling, when the control is released it does 905not return to reading from automation data. 906\end{description} 907Here is a screenshot of automation WRITE mode, and some automation 908data, with the track pane automation popup menu showing (see track 909automation \ref{track_attr_automation}): 910\begin{figure}[htp] 911\centering \includegraphics[width=\screenshotwidth] 912{pics/main_window_with_automation} 913\caption{Audio automation graphs} 914\label{fig:audio_automation} 915\end{figure} 916 917\label{midi_automation} \subsection{Midi automation} 918MIDI automation is a slightly different concept: Unlike audio 919automation, currently there is no automation 'mode' and it doesn't 920record graphical control movements. Data is viewed from within 921the pianoroll and drum editors, by clicking on the 'Ctrl' button %% FIXME Ref to pianoroll 922on those canvases. 923 924Similar to audio controls, each midi control has a manual adjustment 925value. This value is overridden when there is midi automation data. 926 927There are a few ways to enter MIDI automation data: 928\begin{itemize} 929\item By adjusting external MIDI controls (such as a midi keyboard 930pitch or modulation wheel) while the transport is rolling and both 931the transport and midi track are in record mode. MusE will record 932the exact movements. As mentioned earlier, note that graphical control 933movements are not recorded. %% FIXME Feature requests for true midi automation 934\item By right-clicking any midi control and choosing an operation 935from the automation popup menu. This includes storing and erasing 936automation events. %% FIXME Store/erase not enough functionality 937\item By adjusting volume, pan, bank or program boxes in the midi 938trackinfo panel and clicking the corresponding volume, pan, or 939program buttons. (See midi trackinfo \ref{midi_trackinfo_sidebar}). 940\item By drawing the data on a midi part's automation graphs. 941\end{itemize} 942Here is a screen shot of a midi track, containing a midi part 943which has been opened with the pianoroll editor and automation %% FIXME Ref to pianoroll 944data showing. 945 946The 'Ctrl' popup menu (bottom left) shows available midi controllers 947and the green dot indicates there is some data. 948 949\begin{figure}[htp] 950\centering \includegraphics[width=\screenshotwidth] 951{pics/main_window_with_midi_automation} 952\caption{MIDI automation graphs} 953\label{fig:midi_automation} 954\end{figure} 955 956 957\section{Configuration} 958 959\subsection{MIDI ports} 960MIDI ports provide an abstraction layer for your MIDI hardware and 961synthesizers (which can be both software and hardware synthesizers), 962and other MIDI applications. Port are numbered. In order to produce 963sound, each MIDI track is assigned to exactly one MIDI port, to which 964the MIDI events are then sent. 965 966The advantage of this abstraction layer is that if your system changes, 967for example you change MIDI hardware, then you need only modify the 968ports instead of all the tracks using those ports. This is similar 969to the audio input and output track abstraction to the outside world. 970 971\label{midi_port_config} \paragraph{MIDI port configuration} 972In the midi/softsynth configuration menu, you must map the port numbers 973to the actual devices (by selecting ALSA or jack midi ports, or synth 974plugins). 975 976Try left-clicking on the "Ports" column of some MIDI track. 977If you use a soft synth, right-clicking the Ports column of the synth 978or any track using the synth lets you launch the synth's GUI. 979 980\begin{figure}[htp] 981\centering \includegraphics[width=\screenshotwidth] 982{pics/midi_config_window} 983\caption{Midi configuration window} 984\label{fig:midi_config_window} 985\end{figure} 986 987\paragraph{Columns in the MIDI configuration ports list:} 988\begin{description} 989\item [{GUI:}] For synthesizer devices, indicates if a gui is available 990and if it is showing. Click to show. 991\item [{I:}] If present, the port can accept MIDI input. Click to 992enable or disable it. 993\item [{O:}] If present, the port can send MIDI output. Click to enable 994or disable it. 995\item [{Instrument:}] Selects the instrument to be used when MIDI is 996played through the port. 997\item [{Device name:}] Selects or creates a MIDI device assigned to the 998port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is 999enabled), or soft synthesizers. Jack MIDI devices are created by selecting 1000Create Jack Device from the Device name drop-down menu. Jack MIDI devices 1001can be renamed as you wish by clicking the device name. Soft synthesizers 1002are created by clicking in the soft synthesizer list and then Add 1003Instance. Or you can simply create a new synthesizer track from the 1004arranger track list, or even the mixer menus. 1005\item [{In and Out routes:}] These are for Jack MIDI devices, they are 1006the routes to and from available Jack MIDI ports. Jack may provide 1007different alias names for these ports, you can select which alias 1008is shown. 1009\item [{Default in channels:}] Auto-connect these port channels to 1010new midi or drum tracks. 1011\item [{Default out channel:}] Auto-connect new midi or drum tracks 1012to this channel on the port. 1013\item [{State:}] Indicates the state of the port including any errors 1014opening it. 1015\end{description} 1016 1017\subsection{Global settings} 1018\subsubsection{Audio settings} 1019\paragraph{Minimum control period} 1020Plugins can usually process an arbitrarily small (or large) amount 1021of samples. If some plugin control value changes continuously, to provide 1022ideal listening experience, MusE would need to call the plugin 44100 1023times a second, asking for one single value at a time. With the minimum 1024control period setting, the user can force MusE to ask the plugin for 1025at least N values. Setting this value to 64 would in this situation 1026make MusE call the plugin $689=\frac{44100}{64})$ times a second, 1027asking for 64 values at a time. While doing this will reduce accuracy 1028of control changes, it may also reduce CPU usage, because calling 1029the plugin more often, requesting smaller chunks, is more expensive 1030than calling it seldomly, requesting larger chunks. 1031\subparagraph{Recommendation} 1032If you have no performance problems, or if you want to do the final 1033downmix of your project, set this to a low value. If you're experiencing 1034performance problems, increasing this value might help. 1035 1036\chapter{Appendix} 1037\label{apx_effects_rack} \section{Understanding the effects rack} 1038One must carefully consider how many audio inputs and outputs a plugin 1039has, and how may channels the particular audio track has (1 mono or 10402 stereo), and how MusE uses the plugins in the rack. 1041 1042MusE will try to internally create as many independent copies 1043(instances) of a plugin as necessary, to satisfy the number of channels 1044in the audio track. 1045Basically it divides the number of track channels by the number of 1046plugin audio inputs or outputs to determine how many copies to make. 1047First it examines the number of plugin audio outputs, and if there are 1048none, it will examine the number of audio inputs, and if there are 1049none, it will simply use just one plugin copy. 1050 1051For mono tracks with plugins having more than one audio input or 1052output, MusE uses the first input or output and ignores the rest. 1053 1054For stereo tracks: 1055 1056\begin{tabular}{|c|c|c|c|c|} 1057\hline 1058plugin inputs & outputs & copies & track in route channels & 1059track out route channels\\ 1060\hline 1061\hline 10620 & 0 & 1 & 0 & 0\\ 1063\hline 10640 & 1 & 2 & 0 & 2\\ 1065\hline 10660 & >=2 & 1 & 0 & 2\\ 1067\hline 10681 & 0 & 2 & 2 & 0\\ 1069\hline 10701 & 1 & 2 & 2 & 2\\ 1071\hline 10721 & >=2 & 1 & 1 (L only) & 2\\ 1073\hline 1074>=2 & 0 & 1 & 2 & 0\\ 1075\hline 1076>=2 & 1 & 2 & 2 & 2\\ 1077\hline 1078>=2 & >=2 & 1 & 2 & 2\\ 1079\hline 1080\end{tabular} 1081 1082Notice that on a stereo track with a plugin having one audio input and 1083two audio outputs, only the first track input route channel is used 1084(left only). 1085 1086These same rules apply to inter-plugin audio when more than one plugin 1087is in the rack chain. Extra audio outputs of one plugin may be ignored 1088by the next plugin if not used. 1089 1090Currently specialized plugins with many inputs and/or outputs are not 1091really useful in MusE. 1092 1093Nor are so-called 'realtime' control plugins which use audio inputs 1094and outputs for control signals. 1095 1096Loud noise alert! Beware of using such plugins in an audio effects 1097rack. 1098 1099Example: Consider a stereo Audio Input track with these effect rack 1100 LADSPA plugins: 1101 1102\begin{itemize} 1103\item comb\_splitter Comb Splitter by Steve Harris 1104\item tap\_stereo\_echo Tap Stereo Echo by Tom Szilagyi 1105\end{itemize} 1106 1107 1108The Comb Splitter has one audio input and two audio outputs. 1109The Stereo Echo has two audio inputs and two audio outputs. 1110 1111The stereo Audio Input track will therefore ignore its second 1112input route connection. It will process the left input only, 1113separating it into stereo with the Comb Splitter, passing the 1114split stereo signal into the Stereo Echo, finally producing 1115stereo output available at the Audio Input track's output routes. 1116 1117 1118One improvement would be not creating unused redundant plugin copies 1119between plugins in stereo tracks. 1120For example, for a plugin having one audio input and one audio output, 1121feeding a plugin having one audio input and two audio outputs, 1122the extra copy of the first plugin is redundant and not required, 1123but currently it is created anyway. 1124\end{document} 1125 1126