beast r4452 - trunk/docs
- From: stw svn gnome org
- To: svn-commits-list gnome org
- Subject: beast r4452 - trunk/docs
- Date: Sun, 16 Mar 2008 09:07:23 +0000 (GMT)
Author: stw
Date: Sun Mar 16 09:07:23 2008
New Revision: 4452
URL: http://svn.gnome.org/viewvc/beast?rev=4452&view=rev
Log:
Added bsewavetool man page, see bug #437469.
Added:
trunk/docs/bsewavetool.1.doxi
Modified:
trunk/docs/Makefile.am
Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am (original)
+++ trunk/docs/Makefile.am Sun Mar 16 09:07:23 2008
@@ -9,6 +9,7 @@
MAN_TARGETS = $(strip \
mans/beast.1 \
mans/bsescm.1 \
+ mans/bsewavetool.1 \
mans/sfidl.1 \
mans/bse.5 \
)
@@ -26,6 +27,7 @@
\
html/beast.1.html \
html/bsescm.1.html \
+ html/bsewavetool.1.html \
html/sfidl.1.html \
html/bse.5.html \
html/coding-style.html \
@@ -231,6 +233,7 @@
bsescm.1.doxi \
plugin-devel.doxi \
sfidl.1.doxi \
+ bsewavetool.1.doxi \
coding-style.doxi \
)
Added: trunk/docs/bsewavetool.1.doxi
==============================================================================
--- (empty file)
+++ trunk/docs/bsewavetool.1.doxi Sun Mar 16 09:07:23 2008
@@ -0,0 +1,348 @@
+ doxer_dnl # emacs: -*- mode: texinfo; texinfo-open-quote: "\""; texinfo-close-quote: "\""; -*-
+ doxer_set{rvstamp,git_author_date,parse_date} $Date: 2007-01-13 20:21:16 +0100 (Sa, 13 Jan 2007) $
+ include @doxer_get{DOXI_INCLUDE_FILE}
+ doxer_set{title} BSEWAVETOOL - BSE Wave Tool
+ doxer_set{man-title} BSEWAVETOOL
+ doxer_set{man-date} @doxer_get{rvstamp}
+ doxer_set{man-source} beast- doxer_get{BST_VERSION}
+ doxer_set{man-manual} BEAST Manual Pages
+
+ heading NAME
+bsewavetool - A tool for editing the native multisample format for @beast and @bse.
+
+ heading SYNOPSIS
+ @manb{bsewavetool} [ mani{tool-options}] command @mani{<file.bsewave>} [ mani{command-arguments}]
+
+ heading DESCRIPTION
+ @manb{bsewavetool} is a command line tool for editing the native
+ multisample format for @beast and @bse, the @mani{bsewave} format.
+ Some common operations are creating new @mani{bsewave} files, adding
+ chunks to an existing file, encoding the sample data, adding meta
+ information or exporting chunks.
+
+ Common uses for @mani{bsewave} files are:
+ @itemize{bullet}
+ @item mapping an individual sample to each midi note (key on the keyboard) -
+ this is mainly useful for drumkits
+ @item approximating the sound of an instrument (such as a piano) by sampling
+ some notes, and mapping these to the corresponding frequencies in a
+ @mani{bsewave} file - when such a file is loaded by @bse and a note is
+ played, @bse will play the "nearest" note, and - if necessary pitch it
+ @done
+
+
+ heading TOOL OPTIONS
+ @itemize{none}
+ @item @manb{-o} @mani{<output.bsewave>} @*
+ Name of the destination file (default: <file.bsewave>).
+ @item @manb{--silent} @*
+ Suppress extra processing information.
+ @item @manb{--skip-errors} @*
+ Skip errors (may overwrite bsewave files after load errors occoured for
+ part of its contents).
+ @item @manb{-h}, @manb{--help} @*
+ Show elaborated help message with command documentation.
+ @item @manb{-v}, @manb{--version} @*
+ Print version information.
+ @done
+
+ heading COMMANDS
+
+ subheading store
+ Store the input bsewave as output bsewave. If both file names are the same,
+ the bsewave file is simply rewritten. Allthough no explicit modifications
+ are performed on the bsewave, externally referenced sample files will be
+ inlined, chunks may be reordered, and other changes related to the bsewave
+ storage process may occour.
+
+ subheading create <n_channels> [options]
+ Create an empty bsewave file, @mani{<n_channels>}=1 (mono) and
+ @mani{<n_channels>}=2 (stereo) are currently supported. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-N} @mani{<wave-name>} @*
+ Name of the wave stored inside of <output.bsewave>.
+ @item @manb{-f} @*
+ Force creation even if the file exists already.
+ @done
+
+ subheading oggenc [options]
+ Compress all chunks with the Vorbis audio codec and store the wave data
+ as Ogg/Vorbis streams inside the bsewave file. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-q} @mani{<n>} @*
+ Use quality level @mani{<n>}, refer to oggenc(1) for details.
+ @done
+
+ subheading add-chunk [options] {-m=midi-note|-f=osc-freq} <sample-file> ...
+ Add a new chunk containing @mani{<sample-file>} to the wave file. For each chunk,
+ a unique oscillator frequency must be given to determine what note the
+ chunk is to be played back for. Multi oscillator frequency + sample-file
+ option combinations may be given on the command line to add multiple wave
+ chunks. The -f and -m options can be omitted for a sample file, if the
+ oscillator frequency can be determined through auto extract options. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency for the next chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--auto-extract-midi-note} @mani{<nth>} @*
+ Automatically retrieve the midi note by extracting the
+ @mani{<nth>} number from the base name of @mani{<sample-file>}.
+ @item @manb{--auto-extract-osc-freq} @mani{<nth>} @*
+ Automatically retrieve the oscillator frequency by
+ extracting the @mani{<nth>} number from the base name
+ of @mani{<sample-file>}.
+ @done
+
+ subheading add-raw-chunk [options] {-m=midi-note|-f=osc-freq} <sample-file> ...
+ Add a new chunk just like with "add-chunk", but load raw sample data.
+ Additional raw sample format options are supported. @*
+
+ @manb{Raw sample format options:}
+ @itemize{none}
+ @item @manb{-R} @mani{<mix-freq>} @*
+ Mixing frequency for the next chunk [44100].
+ @item @manb{-F} @mani{<format>} @*
+ Raw sample format, supported formats are: alaw, ulaw, float,
+ signed-8, signed-12, signed-16, unsigned-8, unsigned-12, unsigned-16 [signed-16].
+ @item @manb{-B} @mani{<byte-order>} @*
+ Raw sample byte order, supported types:
+ little-endian, big-endian [little-endian].
+ @done
+
+ subheading xinfo {-m=midi-note|-f=osc-freq|--chunk-key=key|--all-chunks|--wave} key=[value] ...
+ Add, change or remove an XInfo string of a bsewave file.
+ Omission of [value] deletes the XInfo associated with the key.
+ Key and value pairs may be specified multiple times, optionally preceeded
+ by location options to control what portion of a bsewave file (the wave,
+ individual wave chunks or all wave chunks) should be affected. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks.
+ @item @manb{--all-chunks} @*
+ Apply XInfo modification to all chunks.
+ @item @manb{--wave} @*
+ Apply XInfo modifications to the wave itself.
+ @done
+
+ subheading info {-m=midi-note|-f=osc-freq|--chunk-key=key|--all-chunks|--wave} [options]
+ Print information about the chunks of a bsewave file. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--all-chunks} *
+ Show information for all chunks (default).
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks.
+ @item @manb{--wave} @*
+ Show information for the wave.
+ @item @manb{--pretty}=medium @*
+ Use human readable format (default).
+ @item @manb{--pretty}=full @*
+ Use human readable format with all details.
+ @item @manb{--script} @mani{<field1>},@mani{<field2>},@mani{<field3>},...,@mani{<fieldN>} @*
+ Use script readable line based space separated output.
+ @done
+ @manb{Valid wave or chunk fields:}
+ @itemize{none}
+ @item channels @* Number of channels.
+ @item label @* User interface label.
+ @item blurb @* Associated comment.
+ @done
+ @manb{Valid wave fields:}
+ @itemize{none}
+ @item authors @* Authors who participated in creating the wave file.
+ @item license @* License specifying redistribution and other legal terms.
+ @item play-type @* Set of required play back facilities for a wave.
+ @done
+ @manb{Valid chunk fields:}
+ @itemize{none}
+ @item osc-freq @* Frequency of the chunk.
+ @item mix-freq @* Sampling rate of the chunk.
+ @item midi-note @* Midi note of a chunk.
+ @item length @* Length of the chunk in sample frames.
+ @item volume @* Volume at which the chunk is to be played.
+ @item format @* Storage format used to save the chunk data.
+ @item loop-type @* Whether the chunk is to be looped.
+ @item loop-start @* Offset in sample frames for the start of the loop.
+ @item loop-end @* Offset in sample frames for the end of the loop.
+ @item loop-count @* Maximum limit for how often the loop should be repeated.
+ @done
+ @manb{Chunk fields that can be computed for the signal:}
+ @itemize{none}
+ @item +avg-energy-raw @* Average signal energy (dB) of the raw data of the chunk.
+ @item +avg-energy @* Average signal energy (dB) using volume xinfo.
+ @done
+
+ The script output consists of one line per chunk. The individual fields
+ of a line are separated by a single space. Special characters are escaped,
+ such as spaces, tabs, newlines and backslashes. So each line of script
+ parsable output can be parsed using the read(P) shell command.
+ Optional fields will printed as a single (escaped) space. @*
+
+ The human readable output formats (--pretty) may vary in future versions
+ and are not recommended as script input.
+
+ subheading clip {-m=midi-note|-f=osc-freq|--chunk-key=key|--all-chunks} [options]
+
+ Clip head and or tail of a wave chunk and produce fade-in ramps at the
+ beginning. Wave chunks which are clipped to an essential 0-length will
+ automatically be deleted. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks.
+ @item @manb{--all-chunks} @*
+ Try to clip all chunks.
+ @item @manb{-s}= mani{<threshold>} @*
+ Set the minimum signal threshold (0..32767) [16].
+ @item @manb{-h}= mani{<head-samples>} @*
+ Number of silence samples to verify at head [0].
+ @item @manb{-t}= mani{<tail-samples>} @*
+ Number of silence samples to verify at tail [0].
+ @item @manb{-f}= mani{<fade-samples>} @*
+ Number of samples to fade-in before signal starts [16].
+ @item @manb{-p}= mani{<pad-samples>} @*
+ Number of padding samples after signal ends [16].
+ @item @manb{-r}= mani{<tail-silence>} @*
+ Number of silence samples required at tail to allow tail clipping [0].
+ @done
+
+ subheading normalize {-m=midi-note|-f=osc-freq|--chunk-key=key|--all-chunks} [options]
+ Normalize wave chunk. This is used to extend (or compress) the signal
+ range to optimally fit the available unclipped dynamic range. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks.
+ @item @manb{--all-chunks} @*
+ Try to normalize all chunks.
+ @done
+
+ subheading loop {-m=midi-note|-f=osc-freq|--all-chunks} [options]
+ Find suitable loop points. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks
+ @item @manb{--all-chunks} @*
+ Try to loop all chunks
+ @done
+
+ subheading highpass [options]
+ Apply highpass filter to wave data.
+
+ @itemize{none}
+ @item @manb{--cutoff-freq} @mani{<f>} @*
+ Filter cutoff frequency in Hz
+ @item @manb{--order} @mani{<o>} @*
+ Filter order [64]
+ @done
+
+ subheading lowpass [options]
+ Apply lowpass filter to wave data.
+
+ @itemize{none}
+ @item @manb{--cutoff-freq} @mani{<f>} @*
+ Filter cutoff frequency in Hz
+ @item @manb{--order} <o> @*
+ Filter order [64]
+ @done
+
+ subheading upsample2 [options]
+ Resample wave data to twice the sampling frequency.
+
+ @itemize{none}
+ @item @manb{--precision} @mani{<bits>} @*
+ Set resampler precision bits [24]. @*
+ Supported precisions: 1, 8, 12, 16, 20, 24
+ (1 is a special value for linear interpolation)
+ @done
+
+ subheading downsample2 [options]
+ Resample wave data to half the sampling frequency.
+
+ @itemize{none}
+ @item @manb{--precision} @mani{<bits>} @*
+ Set resampler precision bits [24]. @*
+ Supported precisions: 1, 8, 12, 16, 20, 24
+ (1 is a special value for linear interpolation).
+ @done
+
+ subheading export {-m=midi-note|-f=osc-freq|--chunk-key=key|--all-chunks|-x=filename} [options]
+ Export chunks from bsewave as WAV file. @*
+
+ @manb{Options:}
+ @itemize{none}
+ @item @manb{-x} @mani{<filename>} @*
+ Set export filename (supports %N %F and %C, see below).
+ @item @manb{-f} @mani{<osc-freq>} @*
+ Oscillator frequency to select a wave chunk.
+ @item @manb{-m} @mani{<midi-note>} @*
+ Alternative way to specify oscillator frequency.
+ @item @manb{--chunk-key} @mani{<key>} @*
+ Select wave chunk using chunk key from list-chunks.
+ @item @manb{--all-chunks} @*
+ Try to export all chunks.
+ @done
+ The export filename can contain the following extra information:
+ @itemize{none}
+ @item %F @* The frequency of the chunk.
+ @item %N @* The midi note of the chunk.
+ @item %C @* Cent detuning of the midi note.
+ @done
+
+ subheading list-chunks [options]
+ Prints a list of chunk keys of the chunks contained in the bsewave file.
+ A chunk key for a given chunk identifies the chunk uniquely and stays valid
+ if other chunks are inserted and deleted. @*
+
+ This bash script shows the length of all chunks (like info --all-chunks): @*
+ @doxer_dnl doxer does not preserve backticks (`), so we use bash $() instead
+ @doxer_dnl doxer cannot do @example here (due to man backend I suppose),
+ @doxer_dnl it seems that enclosing the section in
+ @doxer_dnl .nf
+ @doxer_dnl .fi
+ @doxer_dnl would be the right thing to do from a man point of view - however
+ @doxer_dnl written with ;, the shell script is usable even without proper
+ @doxer_dnl indentation
+ for key in $(bsewavetool list-chunks foo.bsewave) ;
+ do
+ bsewavetool info foo.bsewave --chunk-key $key --script length ;
+ done
+
+ heading SEE ALSO
+ uri{beast 1 html,beast(1)} @*
+ longuri{http://beast.gtk.org, BEAST/BSE Website} @*
+ longuri{http://beast.gtk.org/architecture#section-samples-and-wave-files, Samples and Waves in BEAST}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
