diff options
28 files changed, 986 insertions, 1533 deletions
diff --git a/muse2/CMakeLists.txt b/muse2/CMakeLists.txt index 9317346f..71e56f04 100644 --- a/muse2/CMakeLists.txt +++ b/muse2/CMakeLists.txt @@ -24,7 +24,6 @@ include(FindPkgConfig) include(CheckIncludeFile) include(cmake/Summary.cmake) -include(cmake/TargetDoc.cmake) project(muse) CMAKE_MINIMUM_REQUIRED(VERSION 2.4.1) @@ -179,12 +178,6 @@ include(${QT_USE_FILE}) ## ## -## find doxygen program -## - -FIND_PROGRAM(DOXY doxygen) - -## ## find ladspa.h ## @@ -459,7 +452,7 @@ set(CMAKE_CXX_FLAGS_DEBUG "-g -DQT_DEBUG -fPIC ${CMAKE_CXX_FLAGS_DEBUG}") # NOTE: share/ directory needs to be at the end so that the translations # are scanned before coming to share/locale -subdirs(al awl grepmidi man plugins muse synti packaging utils demos share) +subdirs(doc al awl grepmidi man plugins muse synti packaging utils demos share) ## Install doc files file (GLOB doc_files @@ -495,10 +488,6 @@ add_custom_target(uninstall message("\n") -if (${DOXY} STREQUAL "DOXY-NOTFOUND") - message("** ERROR: The program 'doxygen' is required, but was not found.") -endif (${DOXY} STREQUAL "DOXY-NOTFOUND") - if (NOT ALSA_FOUND) message("** ERROR: alsa >= 0.9.0 is required, but development files were not found.") endif (NOT ALSA_FOUND) diff --git a/muse2/ChangeLog b/muse2/ChangeLog index c1696aaa..04a81592 100644 --- a/muse2/ChangeLog +++ b/muse2/ChangeLog @@ -1,3 +1,12 @@ +22.02.2013: + * New: Install pre-built PDF + single/split HMTL docs. Separate devel docs. Added build script. (Tim) + Build script is /doc/build_docs.sh You'll want to use it or a variant to get the HTML .aux files. + Fixed table in my Appendix in tex file so it works with HTML. + - For now, I've changed F1 help to open PDF, if not found fallback to HTML. + I've #define MUSE_USE_PDF_HELP_FILE in help.cpp. Undefine for HTML only. + May at least need to keep track of viewer process (don't open copies), also try context-sensitive help. + Help opener always been LANG ready (looks for _xx) but this new build script is not 'automatic'. + - TODO: For some reason the generated HTML developer docs contain nonsense. (Unknown formatters?) 21.02.2013: - Fixed: Multiple label warnings in the LaTeX doc. Reference and formatting fixes. (Orcan) - Improved: Table of contents and hyperrefs in te LaTeX doc. (Orcan) diff --git a/muse2/README b/muse2/README index a39a19b0..925e3381 100644 --- a/muse2/README +++ b/muse2/README @@ -20,9 +20,6 @@ details. Requirements: ============================= - - doxygen - www.doxygen.org - - CMake >= 2.4 http:/www.cmake.org/HTML/Download.html @@ -47,7 +44,12 @@ details. e2fsprogs package http://e2fsprogs.sourceforge.net/ Some distros may include it in another package such as 'libuuid', or offer a choice. + - LADSPA (development file ladspa.h) + www.ladspa.org + + ============================= Optional: + ============================= - fluidsynth >= 1.0.3 (formerly known as iiwusynth) (development files) http://sourceforge.net/apps/trac/fluidsynth/ @@ -66,10 +68,6 @@ details. Recently LADISH has been emulating it instead: http://ladish.org/ - - ConTeXt (for building documentation, by default the build - script tries to build documentation, can be - disabled by setting ENABLE_DOCUMENTATION to OFF) - - Python The python scripting language http://www.python.org Python support is required for some experimental features. diff --git a/muse2/doc/CMakeLists.txt b/muse2/doc/CMakeLists.txt new file mode 100644 index 00000000..de90563e --- /dev/null +++ b/muse2/doc/CMakeLists.txt @@ -0,0 +1,75 @@ +#============================================================================= +# MusE +# Linux Music Editor +# $Id:$ +# +# Copyright (C) 1999-2013 by Werner Schweer and others +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the +# Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +#============================================================================= + +install( FILES pdf/documentation.pdf pdf/developer_docs.pdf + DESTINATION ${MusE_DOC_DIR}/muse_pdf + ) + +file (GLOB single_documentation_html_files + html/single/documentation/*.css + html/single/documentation/*.html + # html/single/documentation/*.jpg + html/single/documentation/*.png + # html/single/documentation/toc_.txt + ) + +file (GLOB single_developer_docs_html_files + html/single/developer_docs/*.css + html/single/developer_docs/*.html + # html/single/developer_docs/*.jpg + html/single/developer_docs/*.png + # html/single/developer_docs/toc_.txt + ) + +file (GLOB split_documentation_html_files + html/split/documentation/*.css + html/split/documentation/*.html + # html/split/documentation/*.jpg + html/split/documentation/*.png + # html/split/documentation/toc_.txt + ) + +file (GLOB split_developer_docs_html_files + html/split/developer_docs/*.css + html/split/developer_docs/*.html + # html/split/developer_docs/*.jpg + html/split/developer_docs/*.png + # html/split/developer_docs/toc_.txt + ) + +install( FILES ${single_documentation_html_files} + DESTINATION ${MusE_DOC_DIR}/muse_html/single/documentation + ) + +install( FILES ${single_developer_docs_html_files} + DESTINATION ${MusE_DOC_DIR}/muse_html/single/developer_docs + ) + +install( FILES ${split_documentation_html_files} + DESTINATION ${MusE_DOC_DIR}/muse_html/split/documentation + ) + +install( FILES ${split_developer_docs_html_files} + DESTINATION ${MusE_DOC_DIR}/muse_html/split/developer_docs + ) +
\ No newline at end of file diff --git a/muse2/doc/build_docs.sh b/muse2/doc/build_docs.sh new file mode 100755 index 00000000..fe9fe231 --- /dev/null +++ b/muse2/doc/build_docs.sh @@ -0,0 +1,129 @@ +#!/bin/bash +#============================================================================= +# MusE +# Linux Music Editor +# Copyright (C) 1999-2013 by Werner Schweer and others +# +# build_docs.sh Copyright (C) 2013 Tim E. Real <terminator356 at users dot sourceforge dot net> +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the +# Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +#============================================================================= + +#============================================================= +# +# Run this script to re-create the PDF and HTML documentation. +# Usage: build_docs.sh [--help] [--no_post_clean] +# +#============================================================= + +if [ "$1" == "--help" ]; then + echo "Usage: build_docs.sh [--no_post_clean (don't clean up after build)]" + exit 1 +fi + +# +# Pre clean +# +rm -rf pdf/*.* +rm -rf html/single/documentation/*.* +rm -rf html/single/developer_docs/*.* +rm -rf html/split/documentation/*.* +rm -rf html/split/developer_docs/*.* +rm -rf tmp + +mkdir -p tmp/pdf/documentation +mkdir -p tmp/pdf/developer_docs + +mkdir -p tmp/html/single/documentation +mkdir -p tmp/html/single/developer_docs +mkdir -p tmp/html/split/documentation +mkdir -p tmp/html/split/developer_docs + +# +# Run the PDF conversions first to get the *.aux files required for proper HTML links displaying +# Run each conversion at least three times to resolve all references +# +# pdflatex -output-directory=pdf documentation.tex +# pdflatex -output-directory=pdf documentation.tex +# pdflatex -output-directory=pdf documentation.tex +# +# pdflatex -output-directory=pdf developer_docs.tex +# pdflatex -output-directory=pdf developer_docs.tex +# pdflatex -output-directory=pdf developer_docs.tex + +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex + +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex +pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex + +# +# Now run the HTML conversions +# +# latex2html -nonavigation -noaddress -noinfo -split 0 -external_file pdf/documentation -dir html/single/documentation documentation.tex +# latex2html -nonavigation -noaddress -noinfo -split 0 -external_file pdf/developer_docs -dir html/single/developer_docs developer_docs.tex +# latex2html -noaddress -noinfo -split 4 -external_file pdf/documentation -dir html/split/documentation documentation.tex +# latex2html -noaddress -noinfo -split 4 -external_file pdf/developer_docs -dir html/split/developer_docs developer_docs.tex + +latex2html -nonavigation -noaddress -noinfo -split 0 -external_file tmp/pdf/documentation/documentation -mkdir -dir tmp/html/single/documentation documentation.tex +latex2html -nonavigation -noaddress -noinfo -split 0 -external_file tmp/pdf/developer_docs/developer_docs -mkdir -dir tmp/html/single/developer_docs developer_docs.tex + +latex2html -noaddress -noinfo -split 4 -external_file tmp/pdf/documentation/documentation -mkdir -dir tmp/html/split/documentation documentation.tex +latex2html -noaddress -noinfo -split 4 -external_file tmp/pdf/developer_docs/developer_docs -mkdir -dir tmp/html/split/developer_docs developer_docs.tex + +# +# Move the files +# +mv -f tmp/pdf/documentation/*.pdf pdf +mv -f tmp/pdf/developer_docs/*.pdf pdf + +mv -f tmp/html/single/documentation/*.css html/single/documentation +mv -f tmp/html/single/documentation/*.html html/single/documentation +# mv -f tmp/html/single/documentation/*.jpg html/single/documentation +mv -f tmp/html/single/documentation/*.png html/single/documentation +# mv -f tmp/html/single/documentation/toc_.txt html/single/documentation + +mv -f tmp/html/single/developer_docs/*.css html/single/developer_docs +mv -f tmp/html/single/developer_docs/*.html html/single/developer_docs +# mv -f tmp/html/single/developer_docs/*.jpg html/single/developer_docs +mv -f tmp/html/single/developer_docs/*.png html/single/developer_docs +# mv -f tmp/html/single/developer_docs/toc_.txt html/single/developer_docs + +mv -f tmp/html/split/documentation/*.css html/split/documentation +mv -f tmp/html/split/documentation/*.html html/split/documentation +# mv -f tmp/html/split/documentation/*.jpg html/split/documentation +mv -f tmp/html/split/documentation/*.png html/split/documentation +# mv -f tmp/html/split/documentation/toc_.txt html/split/documentation + +mv -f tmp/html/split/developer_docs/*.css html/split/developer_docs +mv -f tmp/html/split/developer_docs/*.html html/split/developer_docs +# mv -f tmp/html/split/developer_docs/*.jpg html/split/developer_docs +mv -f tmp/html/split/developer_docs/*.png html/split/developer_docs +# mv -f tmp/html/split/developer_docs/toc_.txt html/split/developer_docs + +# +# Post clean +# +if [ "$1" != "--no_post_clean" ]; then +# rm -f pdf/*.aux pdf/*.log pdf/*.out pdf/*.toc +# rm -f html/single/documentation/*.aux html/single/documentation/*.log html/single/documentation/*.out html/single/documentation/*.pl html/single/documentation/*.tex html/single/documentation/WARNINGS +# rm -f html/single/developer_docs/*.aux html/single/developer_docs/*.log html/single/developer_docs/*.out html/single/developer_docs/*.pl html/single/developer_docs/*.tex html/single/developer_docs/WARNINGS +# rm -f html/split/documentation/*.aux html/split/documentation/*.log html/split/documentation/*.out html/split/documentation/*.pl html/split/documentation/*.tex html/split/documentation/WARNINGS +# rm -f html/split/developer_docs/*.aux html/split/developer_docs/*.log html/split/developer_docs/*.out html/split/developer_docs/*.pl html/split/developer_docs/*.tex html/split/developer_docs/WARNINGS +rm -rf tmp +fi diff --git a/muse2/doc/developer_docs.tex b/muse2/doc/developer_docs.tex new file mode 100644 index 00000000..bc3cdc86 --- /dev/null +++ b/muse2/doc/developer_docs.tex @@ -0,0 +1,702 @@ +%% (c) 2012 florian jung +%% (c) 2012 Robert Jonsson +%% we should consider putting this under a proper license. GPL, or +%% some GPL-like documentation license?? + +%% rules for editing documentation: (READ THIS FIRST) +%% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +%% +%% please try to let newly written lines be shorter than 72 characters. +%% minor exceptions are okay, but please not more than 80 chars. +%% comments shall start after character #80 of the line (that is, +%% they shall be "on the right margin") +%% +%% DON'T MIX up changes and reformatting in one commit. when changing +%% stuff, please don't touch the lines before and after your change +%% (that is, do not re-wrap them), even if it will look a bit patchy. +%% this is for being able to easily use diff. +%% when you want to reformat this file, then do it. but don't change +%% anything, as this would be hard to find in a diff. and clearly +%% state in the commit log that you "only" rearranged things. +%% +%% please adhere to the "User's manual" / "Internals" / "Design" +%% partitioning (genereally, don't change the chapters until there +%% is a really good reason for doing so (adding a chapter like +%% "feature requests" as flo did in r1497 IS one). +%% Below that, feel free to change the logical arrangement +%% (making paragraphs to subsections and similar) if you deem it +%% neccessary. +%% +%% Whenever referring to code symbols, constants or source/header +%% files, please use \sym{someClass::someSymbol}, \usym{UPPERCASE_THING} +%% or \f{file.cpp}. +%% Only specify file paths or namespaces where it would be ambiguous +%% otherwise. Specify 'someClass::' until it would disturb the reader +%% and it is obvious. you have to replace '_' by {\_} (with the {}!). +%% These macros do automatic hyphenation on Camel-Case, under_-score +%% and scope::-operator boundaries. If you need to insert additional +%% hyphenation points, use {\-}. +%% Example: \sym{someClass::someAb{\-}nor{\-}mal{\-}lyLongName} will +%% hyphenate: some-Class::-some-Ab-nor-mal-ly-Long-Name +%% +%% Whenever referring to URLs, please wrap them in \url{blah}. Key +%% combinations shall look like \key{CTRL+C}. Menu items shall look +%% like \menu{Menu > Submenu > Menu Item}. +%% +%% Where possible, reference other parts of this documents with +%% \label and \ref. Avoid duplicate information under "Internals" by +%% referring to the appropriate section in "User's manual". +%% +%% Please do no time-stamping of sections. if you need time-stamps, +%% use "svn blame documentation.tex" +%% +%% If you contribute something, feel free to add yourself to \author. +%% +%% If you don't speak LaTeX fluently, a few tips: +%% * \section, \subsection, \subsubsection, \paragraph, \subparagraph +%% let you create sections etc. just copy-and-paste if unsure. +%% * you must prefix special characters like the underscore with \ +%% (backslash) +%% * \emph{some text} emphasizes the text, printing it italic. +%% * \texttt{some text} displays the text in a typewriter font +%% * \label{someName} creates a label at this position. this doesn't +%% show up in the pdf. with \ref{someName}, you can reference to this +%% label. (LaTeX will insert the section number instead of \ref) +%% For this to work, you might need to recompile the .tex twice. +%% +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Dependencies: +%% To produce pdf output from this document the following packages are +%% needed (atleast under Ubuntu derivatives) +%% latex???-base +%% texlive-latex-recommended +%% texlive-latex-extra +%% +%% To produce a pdf version of this manual type: +%% pdflatex documentation.tex <enter> +%% A file documentation.pdf should be generated. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + + +\documentclass[a4paper]{report} +\usepackage[a4paper, left=2.5cm, right=2.5cm, top=2.5cm, bottom=2.5cm]{geometry} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[english]{babel} +\usepackage{graphicx} +\usepackage{hyphenat} +\usepackage{wrapfig} +\usepackage{fancyhdr} +\usepackage{hyperref} +\usepackage{xcolor} +\hypersetup{ + linkcolor=blue, + urlcolor=blue, + colorlinks=true, % hyperlinks will be blue + linkbordercolor=blue, % hyperlink borders will be blue + %pdfborderstyle={/S/U/W 1} % border style will be underline of width 1pt +} +\pagestyle{fancy} + \lhead{\scriptsize{\slshape\leftmark}} + \chead{} + \rhead{\thepage} + \lfoot{} + \cfoot{} + \rfoot{} + \renewcommand{\headrulewidth}{0.4pt} +\usepackage{ifthen} + +%% Borrowed from Lyx output. "Because html converters don't know +%% tabularnewline". Is required? Maybe replace with \\ ? +\providecommand{\tabularnewline}{\\} + +% Hyphenate symbols before each uppercase letter, after each underscore +% (without a "-") and after each ':' (without a "-") +% TODO for any latex crack: also do automatic hyphenation, that is, +% instead of some-Automation-Expression, do some-Au-to-ma-tion-Ex-press-ion +\makeatletter +\newcommand{\camelhyph}[1]{\@fterfirst\c@amelhyph#1\relax } +\newcommand{\underscorehyph}[1]{\@fterfirst\u@nderscorehyph#1\relax } +\def\@fterfirst #1#2{#2#1} +\def\c@amelhyph #1{% +\ifthenelse{\equal{#1}\relax}{}{% Do nothing if the end has been reached + \ifnum`#1=95 \_\hspace{0pt}\else % Check whether #1 is "_", then print _[thin space] + \ifnum`#1=58 :\hspace{0pt}\else + \ifnum`#1>64 + \ifnum`#1<91 \-#1\else#1\fi% Check whether #1 is an uppercase letter, + \else#1\fi + \fi + \fi + % if so, print \-#1, otherwise #1 + \expandafter\c@amelhyph% % insert \c@amelhyph again. +}} +\def\u@nderscorehyph #1{% +\ifthenelse{\equal{#1}\relax}{}{% Do nothing if the end has been reached + \ifnum`#1=95 \_\hspace{0pt}\else % Check whether #1 is "_", then print _\- + \ifnum`#1=58 :\hspace{0pt}\else#1\fi\fi + \expandafter\u@nderscorehyph% % insert \u@nderscorehyph again. +}} +\makeatother + + + +\author{Florian Jung, Robert Jonsson, Tim Donnelly} +\title{MusE Documentation} + +% Orcan: not needed since the hyperref package takes care of all +%\newcommand{\url}[1]{\texttt{#1}} +\newcommand{\key}[1]{\textbf{#1}} +\newcommand{\shell}[1]{\texttt{\textbf{#1}}} +\newcommand{\menu}[1]{\textbf{#1}} +\newcommand{\sym}[1]{\texttt{\camelhyph{#1}}} +\newcommand{\listing}[1]{\texttt{\camelhyph{#1}}} +\newcommand{\usym}[1]{\texttt{\underscorehyph{#1}}} +\newcommand{\file}[1]{\texttt{\camelhyph{#1}}} +\newcommand{\screenshotwidth}[0]{0.8\textwidth} + +\begin{document} +\tableofcontents +\chapter{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 \emph{why} stuff is done please refer to the following +chapter. + +\section{User interface programming} +We use the QT Toolkit for GUI- and other programming. The \emph{QT-Assistant} +is an important tool for getting help. Almost everything can be looked +up there. + +GUIs can be either be hardcoded (see \file{arranger.cpp} for an example) +or can be created using \emph{QT-Designer} (see the dialogs under +\file{widgets/function_dialogs/} for mostly cleanly-written examples). +Don't forget to add your \file{cpp}, \file{h} and \file{ui} files to the +corresponding sections in the \file{CMakeLists.txt}! + +Additionally, MusE offers some custom widgets, like menu title items etc. +Following, there will be a small, unordered list about custom widgets: +\begin{itemize} +\item \sym{MusEGui::MenuTitleItem}: Provides a title-bar in a \sym{QMenu}. \\ + Usage: \listing{someMenu->addAction(new\ MusEGui::MenuTitleItem(tr("fnord"),\ someMenu));} \\ + Defined in \file{widgets/menutitleitem.h}. +\item \sym{MusEGui::PopupMenu}: Provides a \sym{QMenu}-like menu which + can stay open after the user checks a checkable action.\\ + Usage: just create a \listing{new\ PopupMenu(\ true|false\ )} instead of + a \listing{new\ QMenu()}. (\listing{true} means 'stay open')\\ + Defined in \file{widgets/popupmenu.h}. +\end{itemize} + + +\section{Configuration} \label{portconfig_sucks} +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: +\begin{itemize} +\item (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings +\item (2) Per-Song configuration, like whether to show or hide certain track types in the arranger +\item (3) Something in between, like MIDI port settings etc. They obviously actually are + global configuration issues (or ought to be), but also obviously must be stored + in the song file for portability. (This problem could possibly be solved by + the feature proposal in \ref{symbolic_ports}. +\end{itemize} + +\paragraph{Reading configuration} +\sym{void\ MusECore::readConfiguration(Xml\&,\ bool,\ bool)} in +\file{conf.cpp} is the central point +of reading configuration. It is called when MusE is started first +(by \sym{bool\ MusECore::readConfiguration()}), and also when a +song is loaded. \\ %TODO: call paths! +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 \sym{readConfiguration()}, +you must take care to place your item into the correct section. The code is +divided into the following sections: +\begin{itemize} +\item Global and/or per-song configuration (3) +\item Global configuration (1) +\item Code for skipping obsolete entries +\end{itemize} + +The sections are divided by comments (they contain \texttt{----}, 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. + +\paragraph{Writing configuration} +Global configuration is written using the +\sym{MusEGui::MusE::writeGlobalConfiguration()} functions, while +per-song-config is written by \sym{MusEGui::MusE::writeConfiguration()} +(notice the missing \sym{Global}; both implemented in \file{conf.cpp}). + +\sym{writeConfiguration} is actually just a subset of the code in +\sym{writeGlobalConfiguration}. \textbf{Duplicate code!} % TODO fix that in the sourcecode. + +\paragraph{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 +\sym{MusECore::Song::read} and \sym{::write}, both implemented in +\file{songfile.cpp}. There are no caveats. + +\paragraph{How to add new items} +When adding global configuration items, then add them into the second +block ("global configuration") in \sym{readConfiguration} and into +\sym{writeGlobalConfiguration}. + +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 \sym{readConfiguration}, and into \sym{writeGlobalConfiguration}. + + +%TODO: how to write config, +%TODO: song/global stuff +%TODO: config lesen und schreiben fuer plugingroups + + +\section{User controls and automation} +\subsection{Handling user input} +\subsubsection{Plugins and synthesizers} +\paragraph{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 \sym{PluginGui}, \sym{PluginIBase} +(in \file{plugin.h}) and \sym{OscIF} (in \sym{osc.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. + +\paragraph{Processing the input, recording} +Upon operating a slider, \sym{PluginIBase::setParam} is called, +which usually writes the control change into the ringbuffer +\sym{PluginI::{\_}controlFifo}. (\sym{PluginI::apply()}, +\sym{DssiSynthIF::getData()} will read this ringbuffer and +do the processing accordingly). Furthermore, \sym{AudioTrack::recordAutomation} +is called, which either directly modifies the controller lists or writes +the change into a "to be recorded"-list (\sym{AudioTrack::{\_}recEvents}) +(depending on whether the song is stopped or played). + +The \sym{AudioTrack::{\_}recEvents} list consists of \sym{CtrlRecVal} +items (see \file{ctrl.h}), which hold the following data: +\begin{itemize} +\item the frame where the change occurred +\item the value +\item the type, which can be \usym{ARVT{\_}START}, \usym{ARVT{\_}VAL} or \usym{ARVT{\_}STOP}. + \usym{ARVT{\_}VAL} are written by every \usym{AudioTrack::recordAutomation} + call, \usym{ARVT{\_}START} and \usym{ARVT{\_}STOP} are generated by + \sym{AudioTrack::startAutoRecord} and \sym{stopAutoRecord}, respectively. +\item and the id of the controller which is affected +\end{itemize} +It is processed when the song is stopped. The call path for this is: +\sym{Song::stopRolling} calls \sym{Song::processAutomationEvents} +calls \sym{AudioTrack::processAutomationEvents}. +This function removes the old events from the track's controller list +and replaces them with the new events from \sym{{\_}recEvents}. In +\usym{AUTO{\_}WRITE} mode, just all controller events within the recorded +range are erased; in \usym{AUTO{\_}TOUCH} mode, the \usym{ARVT{\_}START} +and \usym{ARVT{\_}STOP} types of the \sym{CtrlRecVal} events are used +to determine the range(s) which should be wiped. + +\paragraph{How it's stored} +Automation data is kept % this is copied from +in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList}, % "design decisions" -> "automation" +that is, a list of \sym{CtrlList}s, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The \sym{CtrlList} 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 \sym{{\_}curVal} (accessed by \sym{curVal()}), +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. + +\sym{AudioTrack::addController} and \sym{removeController} are used % TODO: swapControllerIDX?? +to add/remove whole controller types; the most important functions which +access \sym{{\_}controller} are: +\begin{itemize} +\item \sym{processAutomationEvents}, \sym{recordAutomation}, + \sym{startAutoRecord}, \sym{stopAutoRecord}: see above. +\item \sym{seekPrevACEvent}, \sym{seekNextACEvent}, \sym{eraseACEvent}, + \sym{eraseRangeACEvents}, \sym{addACEvent}, \sym{changeACEvent}, + which do the obvious +\item \sym{pluginCtrlVal}, \sym{setPluginCtrlVal}: the first + returns the current value according to the \sym{{\_}controller} + list, the second only sets the \sym{curVal}, but does not + insert any events. +\end{itemize} + +Whenever a \sym{CtrlList} has been manipulated, +\sym{MusEGlobal::song->controllerChange(Track{*})} shall be called, +which emits the \sym{MusEGlobal::song->controllerChanged(Track{*})} +signal in order to inform any parts of MusE about the change (currently, +only the arranger's part canvas utilizes this). + +\paragraph{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 \usym{AUTO{\_}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 \usym{AUTO{\_}TOUCH} (and currently (r1492) \usym{AUTO{\_}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 \usym{AUTO{\_}WRITE} mode. + +The responsible functions are: \sym{PluginI::oscControl} and +\sym{DssiSynthIF::oscControl} for handling native GUIs, +\sym{PluginI::ctrlPressed} and \sym{ctrlReleased} for MusE +default GUIs and \sym{PluginI::guiParamPressed}, +\sym{guiParamReleased}, \sym{guiSliderPressed} and +\sym{guiSliderReleased} for MusE GUIs read from a UI file; +\sym{guiSlider{*}} obviously handle sliders, while \sym{guiParam{*}} +handle everything else which is not a slider. They call +\sym{PluginI::enableController} to enable/disable it. + +Furthermore, on every song stop or seek, \sym{PluginI::enableAllControllers} +is called, which re-enables all controllers again. The call paths for +this are: +\begin{itemize} +\item For stop: \sym{Song::stopRolling} calls + \sym{Song::processAutomationEvents} calls + \sym{Song::clearRecAu{\-}to{\-}ma{\-}tion} calls + \sym{Track::clearRecAutomation} calls + \sym{PluginI::enableAllControllers} +\item For seek: \sym{Audio::seek} sends a message ("\sym{G}") to + \sym{Song::seqSignal} which calls + \sym{Song::clearRecAutomation} which calls + \sym{PluginI::enableAllControllers} +\end{itemize} + + + + +\chapter{Design decisions} +\section{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 \sym{PluginI::{\_}controlFifo}. Automation data is kept +in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList}, +that is, a list of \sym{CtrlList}s, that is, a list of lists of +controller-objects which hold the control points of the automation graph. +The \sym{CtrlList} 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 \sym{PluginI::{\_}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 \emph{driver} period. +This might lead to noticeable jumps in value. + +This could possibly be solved in two ways: +\paragraph{Maintaining a slave control list} +This approach would maintain a fully redundant slave control list, +similar to \sym{PluginI::{\_}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 \sym{PluginI::{\_}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). + +\paragraph{Holding iterators} +We also could hold a list of iterators of the single \sym{CtrlList}s. +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. + +\paragraph{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 \emph{every single frame}, we +need to do a binary search on multiple controller lists. + + +\chapter{Feature requests} +\section{Per-Part automation and more on automation} % by flo +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). + +\section{Pre-Rendering tracks} +\subsection{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. + +\emph{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 \emph{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.) + +\subsection{Use cases} +\paragraph{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!) + +\paragraph{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..?) + +\paragraph{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 \emph{full} song with you. + +\paragraph{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). + +\subsection{Possible scenarios} +\paragraph{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. + +\paragraph{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. + +\paragraph{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. + + +\subsection{Extensions} +\paragraph{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. + +\paragraph{Audio export} +As described in the Use cases, MusE can allow you to export your song +in some multitrack audio format. + +\paragraph{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. + +\paragraph{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. + + + +\section{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: +\begin{itemize} +\item A menu bar, containing stuff suitable for the complete window, + which might include window name, MDI-ness etc. +\item A toolbar which contains controls suitable for every single slot. +\item A container with one or more slots; the slots can be scrolled in + y-direction if there are multipe slots. +\item A time-scrollbar with zoom +\end{itemize} + +Each slot contains the following: +\begin{itemize} +\item A menu button, button box or control panel for setting up this + particular slot. This could contain "note head colors", "show + a transposing instrument" etc for score edit slots, "event + rectangle color", "grid size" and "snap to grid" for pianoroll/ + drum editors. +\item The actual canvas +\item A y-direction scroll bar, possibly with zoom control (for + pianoroll editor) +\end{itemize} + +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. + +\section{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. + +\section{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 \usym{AUTO{\_}TOUCH} mode. + + + +\section{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? + +\section{Symbolic names for MIDI ports} \label{symbolic_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 \ref{portconfig_sucks}, 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 \emph{every} port +for \emph{every} song. + +\end{document} + +% TODO: song type etc? kill it! +% song len box: same + +% TODO: unified automation and midi ctrls: +% both shall be editable through the same editors +% four modes: 1. discrete +% 2. continous (plus a global and per-port setting for the max rate) +% 3. switch (not necessarily ON/OFF; signals with color plus text annotation) +% 4. raw (no graph, instead a box with the value sent out (for "all voices off") +% they shall be copy-and-pastable, at least between compatible modes +% they shall be slotted, like pianoroll +% maybe also "overlapping", like arranger (?) +% midi recording tries to make out straight lines (like non-ended automation streams) +% + + +% new song (in general: load as template) plus "overwrite port config" +% should re-create the default jack devices and autoconnect them. + +% what's audio aux for? + +% bug in arranger/pcanvas/automation: if a controlpoint is directly on +% a line of another ctrl graph, you can't click it + diff --git a/muse2/doc/documentation.tex b/muse2/doc/documentation.tex index 37dbafc5..a6fe929b 100644 --- a/muse2/doc/documentation.tex +++ b/muse2/doc/documentation.tex @@ -111,10 +111,6 @@ \renewcommand{\headrulewidth}{0.4pt} \usepackage{ifthen} -%% Borrowed from Lyx output. "Because html converters don't know -%% tabularnewline". Is required? Maybe replace with \\ ? -\providecommand{\tabularnewline}{\\} - % Hyphenate symbols before each uppercase letter, after each underscore % (without a "-") and after each ':' (without a "-") % TODO for any latex crack: also do automatic hyphenation, that is, @@ -1058,29 +1054,29 @@ output, MusE uses the first input or output and ignores the rest. For stereo tracks: \begin{tabular}{|c|c|c|c|c|} -\hline +\hline plugin inputs & outputs & copies & track in route channels & -track out route channels\tabularnewline -\hline -\hline -0 & 0 & 1 & 0 & 0\tabularnewline -\hline -0 & 1 & 2 & 0 & 2\tabularnewline -\hline -0 & >=2 & 1 & 0 & 2\tabularnewline -\hline -1 & 0 & 2 & 2 & 0\tabularnewline -\hline -1 & 1 & 2 & 2 & 2\tabularnewline -\hline -1 & >=2 & 1 & 1 (L only) & 2\tabularnewline -\hline ->=2 & 0 & 1 & 2 & 0\tabularnewline -\hline ->=2 & 1 & 2 & 2 & 2\tabularnewline -\hline ->=2 & >=2 & 1 & 2 & 2\tabularnewline -\hline +track out route channels\\ +\hline +\hline +0 & 0 & 1 & 0 & 0\\ +\hline +0 & 1 & 2 & 0 & 2\\ +\hline +0 & >=2 & 1 & 0 & 2\\ +\hline +1 & 0 & 2 & 2 & 0\\ +\hline +1 & 1 & 2 & 2 & 2\\ +\hline +1 & >=2 & 1 & 1 (L only) & 2\\ +\hline +>=2 & 0 & 1 & 2 & 0\\ +\hline +>=2 & 1 & 2 & 2 & 2\\ +\hline +>=2 & >=2 & 1 & 2 & 2\\ +\hline \end{tabular} Notice that on a stereo track with a plugin having one audio input and @@ -1125,544 +1121,5 @@ 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. - - -\chapter{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 \emph{why} stuff is done please refer to the following -chapter. - -\section{User interface programming} -We use the QT Toolkit for GUI- and other programming. The \emph{QT-Assistant} -is an important tool for getting help. Almost everything can be looked -up there. - -GUIs can be either be hardcoded (see \file{arranger.cpp} for an example) -or can be created using \emph{QT-Designer} (see the dialogs under -\file{widgets/function_dialogs/} for mostly cleanly-written examples). -Don't forget to add your \file{cpp}, \file{h} and \file{ui} files to the -corresponding sections in the \file{CMakeLists.txt}! - -Additionally, MusE offers some custom widgets, like menu title items etc. -Following, there will be a small, unordered list about custom widgets: -\begin{itemize} -\item \sym{MusEGui::MenuTitleItem}: Provides a title-bar in a \sym{QMenu}. \\ - Usage: \listing{someMenu->addAction(new\ MusEGui::MenuTitleItem(tr("fnord"),\ someMenu));} \\ - Defined in \file{widgets/menutitleitem.h}. -\item \sym{MusEGui::PopupMenu}: Provides a \sym{QMenu}-like menu which - can stay open after the user checks a checkable action.\\ - Usage: just create a \listing{new\ PopupMenu(\ true|false\ )} instead of - a \listing{new\ QMenu()}. (\listing{true} means 'stay open')\\ - Defined in \file{widgets/popupmenu.h}. -\end{itemize} - - -\section{Configuration} \label{portconfig_sucks} -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: -\begin{itemize} -\item (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings -\item (2) Per-Song configuration, like whether to show or hide certain track types in the arranger -\item (3) Something in between, like MIDI port settings etc. They obviously actually are - global configuration issues (or ought to be), but also obviously must be stored - in the song file for portability. (This problem could possibly be solved by - the feature proposal in \ref{symbolic_ports}. -\end{itemize} - -\paragraph{Reading configuration} -\sym{void\ MusECore::readConfiguration(Xml\&,\ bool,\ bool)} in -\file{conf.cpp} is the central point -of reading configuration. It is called when MusE is started first -(by \sym{bool\ MusECore::readConfiguration()}), and also when a -song is loaded. \\ %TODO: call paths! -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 \sym{readConfiguration()}, -you must take care to place your item into the correct section. The code is -divided into the following sections: -\begin{itemize} -\item Global and/or per-song configuration (3) -\item Global configuration (1) -\item Code for skipping obsolete entries -\end{itemize} - -The sections are divided by comments (they contain \texttt{----}, 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. - -\paragraph{Writing configuration} -Global configuration is written using the -\sym{MusEGui::MusE::writeGlobalConfiguration()} functions, while -per-song-config is written by \sym{MusEGui::MusE::writeConfiguration()} -(notice the missing \sym{Global}; both implemented in \file{conf.cpp}). - -\sym{writeConfiguration} is actually just a subset of the code in -\sym{writeGlobalConfiguration}. \textbf{Duplicate code!} % TODO fix that in the sourcecode. - -\paragraph{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 -\sym{MusECore::Song::read} and \sym{::write}, both implemented in -\file{songfile.cpp}. There are no caveats. - -\paragraph{How to add new items} -When adding global configuration items, then add them into the second -block ("global configuration") in \sym{readConfiguration} and into -\sym{writeGlobalConfiguration}. - -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 \sym{readConfiguration}, and into \sym{writeGlobalConfiguration}. - - -%TODO: how to write config, -%TODO: song/global stuff -%TODO: config lesen und schreiben fuer plugingroups - - -\section{User controls and automation} -\subsection{Handling user input} -\subsubsection{Plugins and synthesizers} -\paragraph{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 \sym{PluginGui}, \sym{PluginIBase} -(in \file{plugin.h}) and \sym{OscIF} (in \sym{osc.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. - -\paragraph{Processing the input, recording} -Upon operating a slider, \sym{PluginIBase::setParam} is called, -which usually writes the control change into the ringbuffer -\sym{PluginI::{\_}controlFifo}. (\sym{PluginI::apply()}, -\sym{DssiSynthIF::getData()} will read this ringbuffer and -do the processing accordingly). Furthermore, \sym{AudioTrack::recordAutomation} -is called, which either directly modifies the controller lists or writes -the change into a "to be recorded"-list (\sym{AudioTrack::{\_}recEvents}) -(depending on whether the song is stopped or played). - -The \sym{AudioTrack::{\_}recEvents} list consists of \sym{CtrlRecVal} -items (see \file{ctrl.h}), which hold the following data: -\begin{itemize} -\item the frame where the change occurred -\item the value -\item the type, which can be \usym{ARVT{\_}START}, \usym{ARVT{\_}VAL} or \usym{ARVT{\_}STOP}. - \usym{ARVT{\_}VAL} are written by every \usym{AudioTrack::recordAutomation} - call, \usym{ARVT{\_}START} and \usym{ARVT{\_}STOP} are generated by - \sym{AudioTrack::startAutoRecord} and \sym{stopAutoRecord}, respectively. -\item and the id of the controller which is affected -\end{itemize} -It is processed when the song is stopped. The call path for this is: -\sym{Song::stopRolling} calls \sym{Song::processAutomationEvents} -calls \sym{AudioTrack::processAutomationEvents}. -This function removes the old events from the track's controller list -and replaces them with the new events from \sym{{\_}recEvents}. In -\usym{AUTO{\_}WRITE} mode, just all controller events within the recorded -range are erased; in \usym{AUTO{\_}TOUCH} mode, the \usym{ARVT{\_}START} -and \usym{ARVT{\_}STOP} types of the \sym{CtrlRecVal} events are used -to determine the range(s) which should be wiped. - -\paragraph{How it's stored} -Automation data is kept % this is copied from -in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList}, % "design decisions" -> "automation" -that is, a list of \sym{CtrlList}s, that is, a list of lists of -controller-objects which hold the control points of the automation graph. -The \sym{CtrlList} 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 \sym{{\_}curVal} (accessed by \sym{curVal()}), -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. - -\sym{AudioTrack::addController} and \sym{removeController} are used % TODO: swapControllerIDX?? -to add/remove whole controller types; the most important functions which -access \sym{{\_}controller} are: -\begin{itemize} -\item \sym{processAutomationEvents}, \sym{recordAutomation}, - \sym{startAutoRecord}, \sym{stopAutoRecord}: see above. -\item \sym{seekPrevACEvent}, \sym{seekNextACEvent}, \sym{eraseACEvent}, - \sym{eraseRangeACEvents}, \sym{addACEvent}, \sym{changeACEvent}, - which do the obvious -\item \sym{pluginCtrlVal}, \sym{setPluginCtrlVal}: the first - returns the current value according to the \sym{{\_}controller} - list, the second only sets the \sym{curVal}, but does not - insert any events. -\end{itemize} - -Whenever a \sym{CtrlList} has been manipulated, -\sym{MusEGlobal::song->controllerChange(Track{*})} shall be called, -which emits the \sym{MusEGlobal::song->controllerChanged(Track{*})} -signal in order to inform any parts of MusE about the change (currently, -only the arranger's part canvas utilizes this). - -\paragraph{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 \usym{AUTO{\_}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 \usym{AUTO{\_}TOUCH} (and currently (r1492) \usym{AUTO{\_}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 \usym{AUTO{\_}WRITE} mode. - -The responsible functions are: \sym{PluginI::oscControl} and -\sym{DssiSynthIF::oscControl} for handling native GUIs, -\sym{PluginI::ctrlPressed} and \sym{ctrlReleased} for MusE -default GUIs and \sym{PluginI::guiParamPressed}, -\sym{guiParamReleased}, \sym{guiSliderPressed} and -\sym{guiSliderReleased} for MusE GUIs read from a UI file; -\sym{guiSlider{*}} obviously handle sliders, while \sym{guiParam{*}} -handle everything else which is not a slider. They call -\sym{PluginI::enableController} to enable/disable it. - -Furthermore, on every song stop or seek, \sym{PluginI::enableAllControllers} -is called, which re-enables all controllers again. The call paths for -this are: -\begin{itemize} -\item For stop: \sym{Song::stopRolling} calls - \sym{Song::processAutomationEvents} calls - \sym{Song::clearRecAu{\-}to{\-}ma{\-}tion} calls - \sym{Track::clearRecAutomation} calls - \sym{PluginI::enableAllControllers} -\item For seek: \sym{Audio::seek} sends a message ("\sym{G}") to - \sym{Song::seqSignal} which calls - \sym{Song::clearRecAutomation} which calls - \sym{PluginI::enableAllControllers} -\end{itemize} - - - - -\chapter{Design decisions} -\section{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 \sym{PluginI::{\_}controlFifo}. Automation data is kept -in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList}, -that is, a list of \sym{CtrlList}s, that is, a list of lists of -controller-objects which hold the control points of the automation graph. -The \sym{CtrlList} 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 \sym{PluginI::{\_}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 \emph{driver} period. -This might lead to noticeable jumps in value. - -This could possibly be solved in two ways: -\paragraph{Maintaining a slave control list} -This approach would maintain a fully redundant slave control list, -similar to \sym{PluginI::{\_}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 \sym{PluginI::{\_}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). - -\paragraph{Holding iterators} -We also could hold a list of iterators of the single \sym{CtrlList}s. -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. - -\paragraph{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 \emph{every single frame}, we -need to do a binary search on multiple controller lists. - - -\chapter{Feature requests} -\section{Per-Part automation and more on automation} % by flo -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). - -\section{Pre-Rendering tracks} -\subsection{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. - -\emph{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 \emph{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.) - -\subsection{Use cases} -\paragraph{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!) - -\paragraph{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..?) - -\paragraph{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 \emph{full} song with you. - -\paragraph{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). - -\subsection{Possible scenarios} -\paragraph{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. - -\paragraph{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. - -\paragraph{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. - - -\subsection{Extensions} -\paragraph{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. - -\paragraph{Audio export} -As described in the Use cases, MusE can allow you to export your song -in some multitrack audio format. - -\paragraph{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. - -\paragraph{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. - - - -\section{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: -\begin{itemize} -\item A menu bar, containing stuff suitable for the complete window, - which might include window name, MDI-ness etc. -\item A toolbar which contains controls suitable for every single slot. -\item A container with one or more slots; the slots can be scrolled in - y-direction if there are multipe slots. -\item A time-scrollbar with zoom -\end{itemize} - -Each slot contains the following: -\begin{itemize} -\item A menu button, button box or control panel for setting up this - particular slot. This could contain "note head colors", "show - a transposing instrument" etc for score edit slots, "event - rectangle color", "grid size" and "snap to grid" for pianoroll/ - drum editors. -\item The actual canvas -\item A y-direction scroll bar, possibly with zoom control (for - pianoroll editor) -\end{itemize} - -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. - -\section{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. - -\section{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 \usym{AUTO{\_}TOUCH} mode. - - - -\section{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? - -\section{Symbolic names for MIDI ports} \label{symbolic_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 \ref{portconfig_sucks}, 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 \emph{every} port -for \emph{every} song. - \end{document} -% TODO: song type etc? kill it! -% song len box: same - -% TODO: unified automation and midi ctrls: -% both shall be editable through the same editors -% four modes: 1. discrete -% 2. continous (plus a global and per-port setting for the max rate) -% 3. switch (not necessarily ON/OFF; signals with color plus text annotation) -% 4. raw (no graph, instead a box with the value sent out (for "all voices off") -% they shall be copy-and-pastable, at least between compatible modes -% they shall be slotted, like pianoroll -% maybe also "overlapping", like arranger (?) -% midi recording tries to make out straight lines (like non-ended automation streams) -% - - -% new song (in general: load as template) plus "overwrite port config" -% should re-create the default jack devices and autoconnect them. - -% what's audio aux for? - -% bug in arranger/pcanvas/automation: if a controlpoint is directly on -% a line of another ctrl graph, you can't click it - diff --git a/muse2/doc/pdf/developer_docs.pdf b/muse2/doc/pdf/developer_docs.pdf Binary files differnew file mode 100644 index 00000000..65b7c1b7 --- /dev/null +++ b/muse2/doc/pdf/developer_docs.pdf diff --git a/muse2/doc/documentation.pdf b/muse2/doc/pdf/documentation.pdf Binary files differindex e14767da..6caa08cf 100644 --- a/muse2/doc/documentation.pdf +++ b/muse2/doc/pdf/documentation.pdf diff --git a/muse2/muse/help.cpp b/muse2/muse/help.cpp index 4bce3a16..e371a6cf 100644 --- a/muse2/muse/help.cpp +++ b/muse2/muse/help.cpp @@ -23,6 +23,7 @@ #include <unistd.h> #include <stdlib.h> +#include <stdio.h> #include <QDesktopServices> #include <QMessageBox> @@ -34,6 +35,9 @@ #include "icons.h" #include "aboutbox_impl.h" +// Whether to open the pdf or the html +#define MUSE_USE_PDF_HELP_FILE + namespace MusEGui { //--------------------------------------------------------- @@ -43,16 +47,44 @@ namespace MusEGui { void MusE::startHelpBrowser() { QString lang(getenv("LANG")); - QString museHelp = DOCDIR + QString("/html/index_") + lang + QString(".html"); - if (access(museHelp.toLatin1(), R_OK) != 0) { - museHelp = DOCDIR + QString("/html/index.html"); - if (access(museHelp.toLatin1(), R_OK) != 0) { - QString info(tr("no help found at: ")); - info += museHelp; - QMessageBox::critical(this, tr("MusE: Open Help"), info); - return; - } + QString museHelp; + bool pdffound = false; + +#ifdef MUSE_USE_PDF_HELP_FILE + museHelp = DOCDIR + QString("/muse_pdf/documentation_") + lang + QString(".pdf"); + if (access(museHelp.toLatin1(), R_OK) != 0) + { + museHelp = DOCDIR + QString("/muse_pdf/documentation.pdf"); + if (access(museHelp.toLatin1(), R_OK) != 0) + { + //QString info(tr("no help found at: ")); + //info += museHelp; + //info += tr("\nTrying HTML file instead...\n"); + //QMessageBox::critical(this, tr("MusE: Open Help"), info); + fprintf(stderr, "MusE::startHelpBrowser() no help found at:%s\nTrying HTML file instead...", + museHelp.toLatin1().constData()); } + else + pdffound = true; + } + else + pdffound = true; +#endif + + if(!pdffound) + { + museHelp = DOCDIR + QString("/muse_html/single/documentation/index_") + lang + QString(".html"); + if (access(museHelp.toLatin1(), R_OK) != 0) { + museHelp = DOCDIR + QString("/muse_html/single/documentation/index.html"); + if (access(museHelp.toLatin1(), R_OK) != 0) { + QString info(tr("no help found at: ")); + info += museHelp; + QMessageBox::critical(this, tr("MusE: Open Help"), info); + return; + } + } + } + launchBrowser(museHelp); } diff --git a/muse2/muse/widgets/canvas.cpp b/muse2/muse/widgets/canvas.cpp index 326992eb..b5df2494 100644 --- a/muse2/muse/widgets/canvas.cpp +++ b/muse2/muse/widgets/canvas.cpp @@ -3,7 +3,7 @@ // Linux Music Editor // $Id: canvas.cpp,v 1.10.2.17 2009/05/03 04:14:01 terminator356 Exp $ // (C) Copyright 1999 Werner Schweer (ws@seh.de) -// Additions, modifications (C) Copyright 2011 Tim E. Real (terminator356 on users DOT sourceforge DOT net) +// Additions, modifications (C) Copyright 2011-2013 Tim E. Real (terminator356 on users DOT sourceforge DOT net) // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License diff --git a/muse2/muse/widgets/canvas.h b/muse2/muse/widgets/canvas.h index d6859a14..06fcd0a6 100644 --- a/muse2/muse/widgets/canvas.h +++ b/muse2/muse/widgets/canvas.h @@ -3,7 +3,7 @@ // Linux Music Editor // $Id: canvas.h,v 1.3.2.8 2009/02/02 21:38:01 terminator356 Exp $ // (C) Copyright 1999 Werner Schweer (ws@seh.de) -// Additions, modifications (C) Copyright 2011 Tim E. Real (terminator356 on users DOT sourceforge DOT net) +// Additions, modifications (C) Copyright 2011-2013 Tim E. Real (terminator356 on users DOT sourceforge DOT net) // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License diff --git a/muse2/share/CMakeLists.txt b/muse2/share/CMakeLists.txt index 3d05e10c..26e011f6 100644 --- a/muse2/share/CMakeLists.txt +++ b/muse2/share/CMakeLists.txt @@ -25,7 +25,6 @@ # are scanned before coming to share/locale subdirs( drummaps - html instruments plugins pybridge diff --git a/muse2/share/html/CMakeLists.txt b/muse2/share/html/CMakeLists.txt deleted file mode 100644 index b9417ad1..00000000 --- a/muse2/share/html/CMakeLists.txt +++ /dev/null @@ -1,33 +0,0 @@ -#============================================================================= -# MusE -# Linux Music Editor -# $Id:$ -# -# Copyright (C) 1999-2011 by Werner Schweer and others -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License -# as published by the Free Software Foundation; either version 2 -# of the License, or (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the -# Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -#============================================================================= - -file (GLOB html_files - *.css - *.html - *.jpg - toc_.txt - ) - -install( FILES ${html_files} - DESTINATION ${MusE_DOC_DIR}/html - ) diff --git a/muse2/share/html/COPYING.html b/muse2/share/html/COPYING.html deleted file mode 100644 index 8c84ced7..00000000 --- a/muse2/share/html/COPYING.html +++ /dev/null @@ -1,353 +0,0 @@ -<qt> -<pre> - Note that the GPL below is copyrighted by the Free Software - Foundation, but the instance of code that it refers to (the - MusE music editor) is copyrighted by me and others who - actually wrote it. - - Werner Schweer - ----------------------------------------- - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - <one line to give the program's name and a brief idea of what it does.> - Copyright (C) 19yy <name of author> - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) 19yy name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - <signature of Ty Coon>, 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. -</pre> -</qt> diff --git a/muse2/share/html/button_bar.jpg b/muse2/share/html/button_bar.jpg Binary files differdeleted file mode 100644 index 204328c8..00000000 --- a/muse2/share/html/button_bar.jpg +++ /dev/null diff --git a/muse2/share/html/getting_started.html b/muse2/share/html/getting_started.html deleted file mode 100644 index 0d6c4344..00000000 --- a/muse2/share/html/getting_started.html +++ /dev/null @@ -1,89 +0,0 @@ -<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor"> -<center><h1>MusE - The Linux (Midi) Music Editor</h1></center> - -<h2>5. Getting Started</h2> -<p> -<h2>5.1 Creating A New Song</h2> -<p> -Here's a very short tutorial on how to create a new song from scratch. - -<p> - -<ol> - <li> Start MusE with the name of a new song (ie. a filename that doesn't -already exist): -<pre> - muse blues1.med -</pre> -Alternatively, start MusE and select <tt>File->New</tt>. The default song -name is <tt>default</tt> and the first time you select <tt>File->Save</tt>, -MusE asks you for a real name. - - <li> Select a song type from the <tt>Type</tt> pulldown menu in the -Toolbar. This selects the capabilities of your MIDI hardware (either -NO, GM, GS, or XG). - - <li> Doubleclick on the first empty track to create a new track. - <li> Select the MIDI channel for the new track; click with the right mouse -button on Ch column in the track list to increment channel nummber, click -with middle mouse button to decrement. - <li> If the TrackInfo window is not visible, press TrackInfo. - <li> Select a MIDI instrument for the MIDI channel of your new track. - <li> Click with the middle mouse button on ruler to set left locator mark. - <li> Click with the right mouse button on the ruler to set right locator mark. -<b>Note:</b> The right mark must be set to the right of the left mark. - <li> Double click between the left and right locators on first track to -create a new part, <b>or</b> select the Pencil tool and draw with the left -mouse button pressed to create a new part. -</ol> - -<p> -<h2>5.2 Recording Events</h2> -<p> -<b>Entering Notes Manually</b> - -<ol> - <li> Select Pointer tool from toolbar - <li> Double click on part in part canvas to start the pianoroll editor - <li> Select Pencil tool from toolbar in the pianoroll editor - <li> Now you can draw events into the event canvas -</ol> - -<p> -<b>Play The Notes</b> - -<ol> - <li> Click with middle mouse button on ruler to set left locator mark - <li> Click with right mouse button on ruler to set right locator mark - <li> Note: right mark must be set right to left mark - <li> Click with left mouse button on ruler to set current position between left and right locator - <li> Select "loop" in the transport toolbar - <li> Press play to start sequencer - <li> You can enter new notes while the sequencer is playing -</ol> - -<p> -<b>Some Hints</b> - -<ol> - <li> You can "play" in realtime on the piano keyboard on the left side of the pianoroll editor - <li> You can change Channel Info and Track Info values during play -</ol> - -<p> -<h2>5.3 Step Recording</h2> -<p> -<ol> - <li> Start the pianoroll editor - <li> Click with left mouse button on ruler to set current position to the start position of your recording - <li> Set the Snap value to the step distance - <li> Set the Quantize value to the length of the notes to record - <li> Enter step record mode by pressing the "S" toolbar button - <li> Every click on the piano keyboard records a note with "Quantize" len and advances the current record position to - <li> The next "Snap" position - <li> Shift+click records a note without advancing the current record position - <li> Change the current position with the cursor keys - <li> Shift+space inserts a gap; all notes to the right of the current position move to the next snap position -</ol> - -</qt> diff --git a/muse2/share/html/index.html b/muse2/share/html/index.html deleted file mode 100644 index c2e5b6a7..00000000 --- a/muse2/share/html/index.html +++ /dev/null @@ -1,66 +0,0 @@ -<html> -<center><h1>MusE - The Linux Music Editor</h1></center> -<p> -<h2>About MusE</h2> - -MusE is a multitrack virtual studio for Linux that has support -for sequencing of both midi and audio and has, among other things, -support for LADSPA, Jack and ALSA. <br> -MusE is written by Werner Schweer and others and is published under the -<a href="COPYING.html"> GNU General Public License</a>. -The latest release of MusE and the <b>up2date documentation</b> can be found at the MusE hompage: -<a href="http://www.muse-sequencer.org/">http://www.muse-sequencer.org/</a>. -<br> -<br> -This is the old manual of the 0.6.3 release but there is already a new one in development, try this: -<a href="http://www.muse-sequencer.org/wiki/index.php/Manual">http://www.muse-sequencer.org/wiki/index.php/Manual</a> - -<p> -<h2>1. Introduction (still to be written)</h2> - -<p> -<h2>2. <a href="installation.html">Installation</a></h2> -<ul> - <li>2.1 How to Obtain MusE - <li>2.2 System Requirements - <li>2.3 Compiliation and Installation -</ul> - -<p> -<h2>3. <a href="invocation.html">Invoking MusE</a></h2> -<ul> - <li>3.1 Invoking MusE - <li>3.2 Command Line Options - <li>3.3 File Types Recognized by MusE -</ul> - -<p> -<h2>4. <a href="window_ref.html">Window Reference Guide</a></h2> -<ul> - <li>4.1 The Main Window - <li>4.2 The Arranger - <li>4.2.1 The Left Pane - <li>4.2.1.1 Track Info - <li>4.2.2 The Right Pane - - <li>4.3 The Button Bar & Menus -</ul> - -<p> -<h2>5. <a href="getting_started.html">Getting Started</a></h2> -<ul> - <li>5.1 Creating A New Song - <li>5.2 Recording Events - <li>5.3 Step Recording -</ul> - -<p> -<h2>6. Mixer Automation (still to be written)</h2> -<ul> - <li>6.1 Record Automation Events (still to be written) -</ul> - - -<p> -<h2>Glossary (still to be written)</h2> -</html> diff --git a/muse2/share/html/installation.html b/muse2/share/html/installation.html deleted file mode 100644 index 19527333..00000000 --- a/muse2/share/html/installation.html +++ /dev/null @@ -1,64 +0,0 @@ -<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor"> -<center><h1>MusE - The Linux (Midi) Music Editor</h1></center> - -<h2>2. Installation</h2> -<p> -<h2>2.1 How to Obtain MusE</h2> -MusE is available at the MusE Homepage, located at -<a href="http://www.muse-sequencer.org/">http://www.muse-sequencer.org/</a>. -Download the latest non-beta release and follow the -installation instructions below. - -<h2>2.2 System Requirements</h2> -To run MusE on your workstation, the following conditions must be met: -<ul> - <li>A GNU/Linux distribution (Red Hat, Debian, etc.) - <li>A working windowing system (most likely X Windows) - <li>qt 2.2 (<a href="http://www.trolltech.com/products/qt">http://www.trolltech.com/products/qt</a>) - <li>gcc 2.95.2 (<a href="http://www.gnu.org/software/gcc/gcc.html">http://www.gnu.org/software/gcc/gcc.html</a>) - <li>glibc 2.1 (<a href="http://ftp.gnu.org/gnu/glibc">http://ftp.gnu.org/gnu/glibc</a>) - <li>Linux kernel configured with RealTimeClock support (<tt>/dev/rtc</tt>) - <li>ALSA (Advanced Linux Sound Architecture) 0.5.9c (it should work with standard OSS drivers as well) - <li>an external midi device -</ul> - -<h2>2.3 Compiliation and Installation</h2> -Unpack the newly-downloaded tarball into a directory and edit -the file <tt>make.inc</tt>. -<p> -The most important variables to set in this file are: -<ul> - <li>QTDIR - <li>ALSA - <li>OSS -</ul> - -Point <tt>QTDIR</tt> to where your QT libraries are installed. -<tt>ALSA</tt> and <tt>OSS</tt> are boolean values (ie. <tt>yes</tt> -or <tt>no</tt>) that tell MusE how to handle Midi and Audio on your -system. It is safe to say <tt>yes</tt> to both. -<p> -A sample config: -<p> -<pre> - QTDIR = /usr/local/qt - ALSA = no - OSS = yes -</pre> - -<p> -When done, save <tt>make.inc</tt> and run the following commands: -<pre> - make depend - make - make install -</pre> - -<p> -Note that <tt>make install</tt> will ask for the <tt>root</tt> password, -as MusE is installed as a setuid-root binary. Setuid-root is needed to allow -MusE to get proper timing functions from the Linux kernel. -<p> -<b>Hint:</b> To get even better timing than that, run MusE with the -R option. - -</qt> diff --git a/muse2/share/html/invocation.html b/muse2/share/html/invocation.html deleted file mode 100644 index 778422c2..00000000 --- a/muse2/share/html/invocation.html +++ /dev/null @@ -1,54 +0,0 @@ -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> - <title>MusE: Linux Music Editor</title> - <link rel="stylesheet" type="text/css" href="styles.css"> -</head> - -<body> -<center><h1>MusE - The Linux (Midi) Music Editor</h1></center> - -<h2>3. Invoking MusE</h2> -<p> -<h2>3.1 Invoking MusE</h2> -MusE is invoked from the command line by typing in: -<pre> - <tt>muse</tt> -</pre> - -Optionally, you can use command line options of the form: - -<pre> - muse <options> <midifile> -</pre> - -<options> : see section 3.2 below for details on options. -<midifile> can be either a standard MIDI file or a MusE -file (*.med, *.med.gz or *.med.bz2). - -<h2>3.2 Command Line Options</h2> -<p> -MusE accepts some options as listed below: -<pre> - -v print version - -d debug mode: no threads - -D debug mode: enable some debug messages - -m debug mode: trace midi Input - -M debug mode: trace midi Output - -s debug mode: trace sync - -R enable real time scheduling -</pre> - -<h2>3.3 File Types Recognized by MusE</h2> -<p> -<table border=1 cellpadding=5> -<tr><td><tt>~/.MusE<td>MusE Configuration File ("~" refers to your home directory) -<tr><td><tt>.musePrj<td>Hidden Project File; stores list of last projects -<tr><td><tt>*.med<td>MusE song file; internal MusE format -<tr><td><tt>*.mid<td>midi file; can be imported -<tr><td><tt>*.kar<td>karaoke: midi file with additional information; some types can be imported -</table> -<p> -With adding the additional extensions <tt>.gz</tt> or <tt>.bz2</tt> -you can read or write compressed files. - -</qt> diff --git a/muse2/share/html/left_pane.jpg b/muse2/share/html/left_pane.jpg Binary files differdeleted file mode 100644 index a659e1ee..00000000 --- a/muse2/share/html/left_pane.jpg +++ /dev/null diff --git a/muse2/share/html/main_window.jpg b/muse2/share/html/main_window.jpg Binary files differdeleted file mode 100644 index eee1e43f..00000000 --- a/muse2/share/html/main_window.jpg +++ /dev/null diff --git a/muse2/share/html/main_window_track_info.jpg b/muse2/share/html/main_window_track_info.jpg Binary files differdeleted file mode 100644 index d4dc207c..00000000 --- a/muse2/share/html/main_window_track_info.jpg +++ /dev/null diff --git a/muse2/share/html/right_pane.jpg b/muse2/share/html/right_pane.jpg Binary files differdeleted file mode 100644 index a770a4e8..00000000 --- a/muse2/share/html/right_pane.jpg +++ /dev/null diff --git a/muse2/share/html/styles.css b/muse2/share/html/styles.css deleted file mode 100644 index 53026fa1..00000000 --- a/muse2/share/html/styles.css +++ /dev/null @@ -1,85 +0,0 @@ -:link { color: #091cef; } -:visited { color: #091cef; } - -body { - background: #eeeeee; - color: #00; - font-family: Arial, Geneva; - font-size: 10pt; - } -h1.head { - margin: 0.05em 0.3em; - font-family: Arial, helvetica, sans-serif; - color: #091cef; - } -td.head { - background: #aeb3e8; - color: #091cef; - } -td.nav { - background: #aeb3e8; - color: #000; - } -td.ld { - background: #aeb3e8; - valign: top; - width: 60; - font-weight: bold; - } -td.lh { - background: #aeb3e8; - } -td.lb { - background: #ced1e2; - } - -h3.navhead { - margin-top: 0.2em; - margin-bottom: 0em; - font-size: small; - font-family: Verdana, Geneva, Arial, sans-serif; - } - -.navlink { - font-size: small; - font-family: Verdana, Geneva, Arial, sans-serif; - } - -p, input { - font-family: Arial, Geneva; - font-size: 10pt; -} - -b { - font-family: Arial, Geneva; - font-size: 10pt; - font-weight: bold; -} - -h1 { - font-family: Arial, Geneva; - font-size: 24pt; - font-weight: bold; -} -h2 { - font-family: Arial, Geneva; - font-size: 18pt; - font-weight: bold; -} - -a { - font-family: Arial, Geneva; - font-size: 12pt; -} - -th { - font-family: Arial, Geneva; - font-size: 10pt; - -} - -td { - font-family: Arial, Geneva; - font-size: 12pt; - color: #000000; - } diff --git a/muse2/share/html/toc_.txt b/muse2/share/html/toc_.txt deleted file mode 100644 index d8503ff4..00000000 --- a/muse2/share/html/toc_.txt +++ /dev/null @@ -1,13 +0,0 @@ -"Glossary" "glossary.html" -"Getting Started" "getting_started.html" -+"Window Reference Guide" "window_ref.html" - +"The Arranger" "window_ref.html" - "The Button Bar & Menus" "window_ref.html" - "The Right Pane" "window_ref.html" - +"The Left Pane" "window_ref.html" - "Track Info" "window_ref.html" - "The Main Window" "window_ref.html" -"Invoking MusE" "invocation.html" -"Installation" "installation.html" -"Introduction" "introduction.html" -"Index" "index.html" diff --git a/muse2/share/html/track_info.jpg b/muse2/share/html/track_info.jpg Binary files differdeleted file mode 100644 index 89834d71..00000000 --- a/muse2/share/html/track_info.jpg +++ /dev/null diff --git a/muse2/share/html/window_ref.html b/muse2/share/html/window_ref.html deleted file mode 100644 index 549e88d3..00000000 --- a/muse2/share/html/window_ref.html +++ /dev/null @@ -1,180 +0,0 @@ -<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor"> -<center><h1>MusE - The Linux (Midi) Music Editor</h1></center> - -<h2>4. Window Reference Guide</h2> -<p> -<h2>4.1 The Main Window</h2> -Here's a screenshot of the main window, with a standard MIDI file already -loaded: -<p> -<img src="main_window.jpg"</img> - -<p> -The main window is basically divided up into two panes separated by a -veritcal bar that is movable horizontally. These two panes together -are called the Arranger. - -<h2>4.2 The Arranger</h2> -<p> -The left pane of the Arranger describes each track in detail, -while the right pane describes each track graphically. - -<h3>4.2.1 The Left Pane</h3> -<img src="left_pane.jpg"</img> -<p> -The left pane details the following information for each track: -<ul> - <li>A -?? - <li>M - Mute the track - <li>C - Defines whether the track is one of MIDI, Drum or Wave. - <li>Track - A freely-editable track name. - <li>Ch - Defines which MIDI Channel this track plays on. - <li>Port - Defines which MIDI port this track plays on. - <li>T -?? -</ul> - -You can select which track is currently "active" by simply clicking -on the track. -<p> -When a track's M column is clicked, that track is marked as Muted with -a red circle and upon playback that track will not be heard. To hear -the track, click on the M column for that track again. -<p> -Right click on the C column for a track to declare the track to be of -type MIDI, Drum or Wave. -<p> -The Track column is free-form, meaning that a double-click on a track's -Track column will allow you to enter a descriptive name for the track, -for example "Hot Lead Guitar". -<p> -The Ch column for a track is changed by right-clicking to increment the -number or middle-clicking to decrement the number. It's generally a -good idea to keep differing instruments on different MIDI channels and it's -considered common to have the drum kit on channel 10. -<p> -<h4>4.2.1.1 Track Info</h4> -<p> -At the bottom of the left pane, you'll see a little button labelled -"TrackInfo". When clicked, the standard information plus more about -the currently selected track is presented: -<p> -<img src="track_info.jpg"</img> -<ul> - <li>Track Name - <li>Channel - <li>Transpose - <li>Delay - <li>Length - <li>Velocity - <li>Compr -</ul> -The bottom half of the TrackInfo display describes MIDI channel information: -<ul> - <li>MIDI Instrument - <li>H-Bank - <li>L-Bank - <li>Progr - <li>Volume - <li>Pan -</ul> - -<p> -Operations that can be performed on the left pane: -<table border=1> -<th> <strong>Track Functions </strong></th> <th> </th> -<tr><td>Select Track<td> - <ul> - <li>Left Mouse Button - </ul> -<tr><td>Select multiple Tracks<td> - <ul> - <li>Shift + Left Mouse Button - </ul> -<tr><td>Change Selected Track<td> - <ul> - <li>Key Up: previous Track - <li>Key Down: next Track - <li>click with left mouse button in name field - </ul> -<tr><td>Move Track<td> - <ul> - <li>Drag with left Mouse Button - </ul> -<tr><td>Create New Track<td> - <ul> - <li>Pulldown Edit<br> - <li>Ctrl T - <li>double click in empty track - </ul> -<tr><td>Delete selected Track(s)<td> - <ul> - <li>Pulldown Edit - <li>Del - </ul> -<tr><td>Rename Track<td> - <ul> - <li>doubleClick with left mouse button - on track name - </ul> -<tr><td>Change Midi Channel<td> - <ul> - <li> left mouse button increments midi channel - <li> middle mouse button decrements midi channel - </ul> -<tr><td>Select Midi Port<td> - <ul> - <li> click with right mouse button on portname; - select from pulldown menu - </ul> -<tr><td>Mute Track<td> - <ul> - <li> click with left mouse button on "M" field in - Tracklist - </ul> -<tr><td>Solo Track<td> - <ul> - <li> click "Solo" button - </ul> -</table> - - -<h2>4.2.2 The Right Pane</h2> -<img src="right_pane.jpg"</img> -<p> -The right pane desribes each track graphically. Time moves from left -to right and is measured in beats that are referenced at the top of -the right pane. Tracks are displayed vertically in boxes, called -"Parts", that depict where MIDI and audio data are played. -<p> -The small sliders that are adjacent to the bottom right corner affect -the view of the right pane in terms of "zooming". The vertical slider -affects the height of the tracks, while the horizontal slider affects -the width. -<p> -Operations that can be performed on the right pane: -<p> -<table border=1> -<tr><td><b>To do this...</b><td><b>...Do this</b> -<tr><td>Select Part<td>Left Click -<tr><td>Select multiple parts<td>Shift + left click -<tr><td>Change selected track<td>Key left: previous part, Key right: next part -<tr><td>Move part<td>Drag with left mouse button -<tr><td>Create new part<td>select Pencil tool; draw with left mouse button pressed, OR set left and right mark; double click on track -<tr><td>Delete selected part(s)<td>select rubber tool; click part to delete -<tr><td>Rename part<td>double click with left mouse button on part -<tr><td>Copy part<td>drag with shift + left mouse button -<tr><td>Cut part<td>select Cut Tool; click on part to cut -<tr><td>Glue part<td>select Glue Tool; click on part to glue with next part -</table> -<p> - -<h2>4.2.3 The Button Bar & Menus</h2> -<img src="button_bar.jpg"</img> -<p> -Across the top, above the Arranger, are a menu system, icons and other -widgets that you use to manipulate your project. Most of these are -self-explanatory, while others are described later in this document. - - - -</qt> |
