From 48b9d2ea9961f935bacabc75a2fbd5cc141010ae Mon Sep 17 00:00:00 2001 From: "Tim E. Real" Date: Fri, 22 Feb 2013 06:46:23 +0000 Subject: New: Install pre-built PDF + single/split HMTL docs. Separate devel docs. Added build script. --- muse2/CMakeLists.txt | 13 +- muse2/ChangeLog | 9 + muse2/README | 12 +- muse2/doc/CMakeLists.txt | 75 +++ muse2/doc/build_docs.sh | 129 +++++ muse2/doc/developer_docs.tex | 702 ++++++++++++++++++++++++++++ muse2/doc/documentation.pdf | Bin 1488360 -> 0 bytes muse2/doc/documentation.tex | 587 +---------------------- muse2/doc/pdf/developer_docs.pdf | Bin 0 -> 226142 bytes muse2/doc/pdf/documentation.pdf | Bin 0 -> 1429504 bytes muse2/muse/help.cpp | 50 +- muse2/muse/widgets/canvas.cpp | 2 +- muse2/muse/widgets/canvas.h | 2 +- muse2/share/CMakeLists.txt | 1 - muse2/share/html/CMakeLists.txt | 33 -- muse2/share/html/COPYING.html | 353 -------------- muse2/share/html/button_bar.jpg | Bin 13115 -> 0 bytes muse2/share/html/getting_started.html | 89 ---- muse2/share/html/index.html | 66 --- muse2/share/html/installation.html | 64 --- muse2/share/html/invocation.html | 54 --- muse2/share/html/left_pane.jpg | Bin 24599 -> 0 bytes muse2/share/html/main_window.jpg | Bin 75510 -> 0 bytes muse2/share/html/main_window_track_info.jpg | Bin 84636 -> 0 bytes muse2/share/html/right_pane.jpg | Bin 34158 -> 0 bytes muse2/share/html/styles.css | 85 ---- muse2/share/html/toc_.txt | 13 - muse2/share/html/track_info.jpg | Bin 14003 -> 0 bytes muse2/share/html/window_ref.html | 180 ------- 29 files changed, 986 insertions(+), 1533 deletions(-) create mode 100644 muse2/doc/CMakeLists.txt create mode 100755 muse2/doc/build_docs.sh create mode 100644 muse2/doc/developer_docs.tex delete mode 100644 muse2/doc/documentation.pdf create mode 100644 muse2/doc/pdf/developer_docs.pdf create mode 100644 muse2/doc/pdf/documentation.pdf delete mode 100644 muse2/share/html/CMakeLists.txt delete mode 100644 muse2/share/html/COPYING.html delete mode 100644 muse2/share/html/button_bar.jpg delete mode 100644 muse2/share/html/getting_started.html delete mode 100644 muse2/share/html/index.html delete mode 100644 muse2/share/html/installation.html delete mode 100644 muse2/share/html/invocation.html delete mode 100644 muse2/share/html/left_pane.jpg delete mode 100644 muse2/share/html/main_window.jpg delete mode 100644 muse2/share/html/main_window_track_info.jpg delete mode 100644 muse2/share/html/right_pane.jpg delete mode 100644 muse2/share/html/styles.css delete mode 100644 muse2/share/html/toc_.txt delete mode 100644 muse2/share/html/track_info.jpg delete mode 100644 muse2/share/html/window_ref.html 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) @@ -178,12 +177,6 @@ include(${QT_USE_FILE}) ## Begin MANDATORY packages... ## -## -## 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 +# +# 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 +%% 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.pdf b/muse2/doc/documentation.pdf deleted file mode 100644 index e14767da..00000000 Binary files a/muse2/doc/documentation.pdf and /dev/null differ 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 new file mode 100644 index 00000000..65b7c1b7 Binary files /dev/null and b/muse2/doc/pdf/developer_docs.pdf differ diff --git a/muse2/doc/pdf/documentation.pdf b/muse2/doc/pdf/documentation.pdf new file mode 100644 index 00000000..6caa08cf Binary files /dev/null and b/muse2/doc/pdf/documentation.pdf differ 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 #include +#include #include #include @@ -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 @@ - -
- 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.
-
-    
-    Copyright (C) 19yy  
-
-    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.
-
-  , 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.
-
- diff --git a/muse2/share/html/button_bar.jpg b/muse2/share/html/button_bar.jpg deleted file mode 100644 index 204328c8..00000000 Binary files a/muse2/share/html/button_bar.jpg and /dev/null differ 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 @@ - -

MusE - The Linux (Midi) Music Editor

- -

5. Getting Started

-

-

5.1 Creating A New Song

-

-Here's a very short tutorial on how to create a new song from scratch. - -

- -

    -
  1. Start MusE with the name of a new song (ie. a filename that doesn't -already exist): -
    -	muse blues1.med
-
    -Alternatively, start MusE and select File->New. The default song -name is default and the first time you select File->Save, -MusE asks you for a real name. - -
  2. Select a song type from the Type pulldown menu in the -Toolbar. This selects the capabilities of your MIDI hardware (either -NO, GM, GS, or XG). - -
  3. Doubleclick on the first empty track to create a new track. -
  4. 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. -
  5. If the TrackInfo window is not visible, press TrackInfo. -
  6. Select a MIDI instrument for the MIDI channel of your new track. -
  7. Click with the middle mouse button on ruler to set left locator mark. -
  8. Click with the right mouse button on the ruler to set right locator mark. -Note: The right mark must be set to the right of the left mark. -
  9. Double click between the left and right locators on first track to -create a new part, or select the Pencil tool and draw with the left -mouse button pressed to create a new part. -
- -

-

5.2 Recording Events

-

-Entering Notes Manually - -

    -
  1. Select Pointer tool from toolbar -
  2. Double click on part in part canvas to start the pianoroll editor -
  3. Select Pencil tool from toolbar in the pianoroll editor -
  4. Now you can draw events into the event canvas -
- -

-Play The Notes - -

    -
  1. Click with middle mouse button on ruler to set left locator mark -
  2. Click with right mouse button on ruler to set right locator mark -
  3. Note: right mark must be set right to left mark -
  4. Click with left mouse button on ruler to set current position between left and right locator -
  5. Select "loop" in the transport toolbar -
  6. Press play to start sequencer -
  7. You can enter new notes while the sequencer is playing -
- -

-Some Hints - -

    -
  1. You can "play" in realtime on the piano keyboard on the left side of the pianoroll editor -
  2. You can change Channel Info and Track Info values during play -
- -

-

5.3 Step Recording

-

-

    -
  1. Start the pianoroll editor -
  2. Click with left mouse button on ruler to set current position to the start position of your recording -
  3. Set the Snap value to the step distance -
  4. Set the Quantize value to the length of the notes to record -
  5. Enter step record mode by pressing the "S" toolbar button -
  6. Every click on the piano keyboard records a note with "Quantize" len and advances the current record position to -
  7. The next "Snap" position -
  8. Shift+click records a note without advancing the current record position -
  9. Change the current position with the cursor keys -
  10. Shift+space inserts a gap; all notes to the right of the current position move to the next snap position -
- - 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 @@ - -

MusE - The Linux Music Editor

-

-

About MusE

- -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.
-MusE is written by Werner Schweer and others and is published under the - GNU General Public License. -The latest release of MusE and the up2date documentation can be found at the MusE hompage: -http://www.muse-sequencer.org/. -
-
-This is the old manual of the 0.6.3 release but there is already a new one in development, try this: -http://www.muse-sequencer.org/wiki/index.php/Manual - -

-

1. Introduction (still to be written)

- -

-

2. Installation

-
    -
  • 2.1 How to Obtain MusE -
  • 2.2 System Requirements -
  • 2.3 Compiliation and Installation -
- -

-

3. Invoking MusE

-
    -
  • 3.1 Invoking MusE -
  • 3.2 Command Line Options -
  • 3.3 File Types Recognized by MusE -
- -

-

4. Window Reference Guide

-
    -
  • 4.1 The Main Window -
  • 4.2 The Arranger -
  • 4.2.1 The Left Pane -
  • 4.2.1.1 Track Info -
  • 4.2.2 The Right Pane - -
  • 4.3 The Button Bar & Menus -
- -

-

5. Getting Started

-
    -
  • 5.1 Creating A New Song -
  • 5.2 Recording Events -
  • 5.3 Step Recording -
- -

-

6. Mixer Automation (still to be written)

-
    -
  • 6.1 Record Automation Events (still to be written) -
- - -

-

Glossary (still to be written)

- 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 @@ - -

MusE - The Linux (Midi) Music Editor

- -

2. Installation

-

-

2.1 How to Obtain MusE

-MusE is available at the MusE Homepage, located at -http://www.muse-sequencer.org/. -Download the latest non-beta release and follow the -installation instructions below. - -

2.2 System Requirements

-To run MusE on your workstation, the following conditions must be met: - - -

2.3 Compiliation and Installation

-Unpack the newly-downloaded tarball into a directory and edit -the file make.inc. -

-The most important variables to set in this file are: -

    -
  • QTDIR -
  • ALSA -
  • OSS -
- -Point QTDIR to where your QT libraries are installed. -ALSA and OSS are boolean values (ie. yes -or no) that tell MusE how to handle Midi and Audio on your -system. It is safe to say yes to both. -

-A sample config: -

-

-	QTDIR = /usr/local/qt
-	ALSA = no
-	OSS = yes
-
- -

-When done, save make.inc and run the following commands: -

-	make depend
-	make
-	make install
-
- -

-Note that make install will ask for the root 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. -

-Hint: To get even better timing than that, run MusE with the -R option. - - 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 @@ - - - MusE: Linux Music Editor - - - - -

MusE - The Linux (Midi) Music Editor

- -

3. Invoking MusE

-

-

3.1 Invoking MusE

-MusE is invoked from the command line by typing in: -
-	muse
-
- -Optionally, you can use command line options of the form: - -
-	muse <options> <midifile>
-
- -<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). - -

3.2 Command Line Options

-

-MusE accepts some options as listed below: -

-   -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
-
- -

3.3 File Types Recognized by MusE

-

- -
~/.MusEMusE Configuration File ("~" refers to your home directory) -
.musePrjHidden Project File; stores list of last projects -
*.medMusE song file; internal MusE format -
*.midmidi file; can be imported -
*.karkaraoke: midi file with additional information; some types can be imported -
-

-With adding the additional extensions .gz or .bz2 -you can read or write compressed files. - - diff --git a/muse2/share/html/left_pane.jpg b/muse2/share/html/left_pane.jpg deleted file mode 100644 index a659e1ee..00000000 Binary files a/muse2/share/html/left_pane.jpg and /dev/null differ diff --git a/muse2/share/html/main_window.jpg b/muse2/share/html/main_window.jpg deleted file mode 100644 index eee1e43f..00000000 Binary files a/muse2/share/html/main_window.jpg and /dev/null differ diff --git a/muse2/share/html/main_window_track_info.jpg b/muse2/share/html/main_window_track_info.jpg deleted file mode 100644 index d4dc207c..00000000 Binary files a/muse2/share/html/main_window_track_info.jpg and /dev/null differ diff --git a/muse2/share/html/right_pane.jpg b/muse2/share/html/right_pane.jpg deleted file mode 100644 index a770a4e8..00000000 Binary files a/muse2/share/html/right_pane.jpg and /dev/null differ 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 deleted file mode 100644 index 89834d71..00000000 Binary files a/muse2/share/html/track_info.jpg and /dev/null differ 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 @@ - -

MusE - The Linux (Midi) Music Editor

- -

4. Window Reference Guide

-

-

4.1 The Main Window

-Here's a screenshot of the main window, with a standard MIDI file already -loaded: -

- - -

-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. - -

4.2 The Arranger

-

-The left pane of the Arranger describes each track in detail, -while the right pane describes each track graphically. - -

4.2.1 The Left Pane

- -

-The left pane details the following information for each track: -

    -
  • A -?? -
  • M - Mute the track -
  • C - Defines whether the track is one of MIDI, Drum or Wave. -
  • Track - A freely-editable track name. -
  • Ch - Defines which MIDI Channel this track plays on. -
  • Port - Defines which MIDI port this track plays on. -
  • T -?? -
- -You can select which track is currently "active" by simply clicking -on the track. -

-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. -

-Right click on the C column for a track to declare the track to be of -type MIDI, Drum or Wave. -

-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". -

-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. -

-

4.2.1.1 Track Info

-

-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: -

- -

    -
  • Track Name -
  • Channel -
  • Transpose -
  • Delay -
  • Length -
  • Velocity -
  • Compr -
-The bottom half of the TrackInfo display describes MIDI channel information: -
    -
  • MIDI Instrument -
  • H-Bank -
  • L-Bank -
  • Progr -
  • Volume -
  • Pan -
- -

-Operations that can be performed on the left pane: - - -
Track Functions  
Select Track -
    -
  • Left Mouse Button -
-
Select multiple Tracks -
    -
  • Shift + Left Mouse Button -
-
Change Selected Track -
    -
  • Key Up: previous Track -
  • Key Down: next Track -
  • click with left mouse button in name field -
-
Move Track -
    -
  • Drag with left Mouse Button -
-
Create New Track -
    -
  • Pulldown Edit
    -
  • Ctrl T -
  • double click in empty track -
-
Delete selected Track(s) -
    -
  • Pulldown Edit -
  • Del -
-
Rename Track -
    -
  • doubleClick with left mouse button - on track name -
-
Change Midi Channel -
    -
  • left mouse button increments midi channel -
  • middle mouse button decrements midi channel -
-
Select Midi Port -
    -
  • click with right mouse button on portname; - select from pulldown menu -
-
Mute Track -
    -
  • click with left mouse button on "M" field in - Tracklist -
-
Solo Track -
    -
  • click "Solo" button -
-
- - -

4.2.2 The Right Pane

- -

-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. -

-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. -

-Operations that can be performed on the right pane: -

- -
To do this......Do this -
Select PartLeft Click -
Select multiple partsShift + left click -
Change selected trackKey left: previous part, Key right: next part -
Move partDrag with left mouse button -
Create new partselect Pencil tool; draw with left mouse button pressed, OR set left and right mark; double click on track -
Delete selected part(s)select rubber tool; click part to delete -
Rename partdouble click with left mouse button on part -
Copy partdrag with shift + left mouse button -
Cut partselect Cut Tool; click on part to cut -
Glue partselect Glue Tool; click on part to glue with next part -
-

- -

4.2.3 The Button Bar & Menus

- -

-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. - - - - -- cgit v1.2.1