trunk/man/wav2gig.1.in

.TH "wav2gig" "1" "03 Sep 2021" "libgig @VERSION@" "libgig tools"
.SH NAME
wav2gig \- Create GigaStudio (.gig) file from a set of WAV files.
.SH SYNOPSIS
.B wav2gig
[ OPTIONS ] GIG_FILE WAV_FILE_OR_DIR_1 [ WAV_FILE_OR_DIR_2 ... ]
.SH DESCRIPTION
Takes a list of wave (.wav) files and / or directories containing wave files as
argument(s) and creates one new GigaStudio / GigaSampler (.gig) file for those
samples.

The created GigaStudio (.gig) file will contain the given input samples. The
samples' meta information (as far as available) like root note
(a.k.a 'unity note'), fine tune, loop points, loop type and loop play count
are automatically extracted from the input wave (.wav) files and applied
accordingly.

Additionally this tool creates exactly one instrument inside the newly created
GigaStudio (.gig) file and tries to automatically map the samples in a
meaningful way to that instrument. As the wave (.wav) format currently does not
support many of the meta information required for this particular task, this
tool tries to extract the required (missing) information from the individual
sample's file name for being able to map the samples accordingly. See
.BR SAMPLE
.BR NAMES
below for details on the assumed naming scheme for input sample files and how
to override that default naming scheme by providing custom regular expression
patterns.

.SH OPTIONS
.TP
.B \ GIG_FILE
GigaStudio / GigaSampler (.gig) filename to be created
.TP
.B \ WAV_FILE_OR_DIR_1
Filename or directory containing wave (.wav) file(s)
.TP
.B \ WAV_FILE_OR_DIR_2
Filename or directory containing wave (.wav) file(s)
.TP
.B \ -r
Recurse through all subdirectories of provided input WAV directories.
.TP
.B \ -f
Overwrite output GigaStudio (.gig) file in case it already exists.
.TP
.B \ -v
Print version and exit.
.TP
.B \ --dry-run
Scan input sample (.wav) files, but exit before creating any .gig file.
.TP
.B \ --verbose
Increase amount of info being shown.
.TP
.B \ --regex-name1 PATTERN
Regular expression for overriding the
.BR NAME1
part of the input sample file name scheme.

Defaults to '([^-\/\\]+) - [^-]+ - [^-]+ - [^-]+ - [^.]+'.

.TP
.B \ --regex-name2 PATTERN
Regular expression for overriding the
.BR NAME2
part of the input sample file name scheme.

Defaults to '[^-\/\\]+ - ([^-]+) - [^-]+ - [^-]+ - [^.]+'.

.TP
.B \ --regex-velocity-nr PATTERN
Regular expression for overriding the
.BR VELOCITY_NR
part of the input sample file name scheme.

Defaults to '[^-\/\\]+ - [^-]+ - ([^-]+) - [^-]+ - [^.]+'.

.TP
.B \ --regex-note-nr PATTERN
Regular expression for overriding the
.BR NOTE_NR
part of the input sample file name scheme.

Defaults to '[^-\/\\]+ - [^-]+ - [^-]+ - ([^-]+) - [^.]+'.

.TP
.B \ --regex-note-name PATTERN
Regular expression for overriding the
.BR NOTE_NAME
part of the input sample file name scheme.

Defaults to '[^-\/\\]+ - [^-]+ - [^-]+ - [^-]+ - ([^.]+)'.

.SH SAMPLE NAMES
By default this tool assumes the following input sample file naming scheme for
automatically mapping samples to regions on the keyboard, as well as mapping
them to velocity splits adequately:

.B 'NAME1 - NAME2 - VELOCITY_NR - NOTE_NR - NOTE_NAME.wav'

Which are interpreted in the following way:

.TP
.B \ NAME1
Primary name of the sample (e.g. "Violin").

This is not interpreted for sample mapping, but it will be used to assemble the
final sample name inside the GigaStudio (.gig) file.

You may use
.BR --regex-name1
to override this part of the naming scheme.

.TP
.B \ NAME2
Secondary name of the sample (e.g. "Cresc").

This is currently ignored, but might be used in future.

You may use
.BR --regex-name2
to override this part of the naming scheme.

.TP
.B \ VELOCITY_NR
MIDI Velocity number of the sample (e.g. "18").

This informtion will be used to automatically create velocity splits.

You may use
.BR --regex-velocity-nr
to override this part of the naming scheme.

.TP
.B \ NOTE_NR
MIDI Note number of the sample (e.g. "021" for note a-1).

This informtion will be used to automatically map the sample to a region on the
keyboard. The sample's root note (a.k.a. "unity note") is taken directly from
the .wav file content, however if the .wav file content does not contain a root
note information then
.B \ NOTE_NR
is used as root note as well.

You may use
.BR --regex-note-nr
to override this part of the naming scheme.

.TP
.B \ NOTE_NAME
Note name of the sample (e.g. "a-1").

This is not interpreted for sample mapping, but it will be used to assemble the
final sample name inside the GigaStudio (.gig) file.

You may use
.BR --regex-note-name
to override this part of the naming scheme.

.PP
This tool utilizes the
.I regular expressions
library provided by C++ (introduced with the C++11 standard revision).
Each custom regular expression (abbreviated as 'RegEx' from now on below)
passed to one of the 
.BR --regex-*
options must contain
.B
exactly one
active RegEx 'capture group' which is denoted in regular expressions by a pair
of round brackets like:

.B (PATTERN)

So the 'capture group' marks the portion in the overall filename string that is
going to be exctracted for the respective component of the filename schema.
If additional RegEx group(s) are needed to build the overall RegEx pattern, then
those other group(s) must be defined as 'passive groups' denoted in RegEx
patterns by an additional question mark and colon like this:

.B (?:PATTERN)

Keep in mind that RegEx scanners behave 'greedy' by default, which means by
default they try to match the longest string possible according to your defined
RegEx pattern. If that's not desired then you may either override the required
parts of your RegEx pattern to behave 'non-greedy' such that those parts would
match for the shortest string possible instead, or alternatively consider using
the RegEx 'alternation'
operator, which is denoted in regular expressions by a vertical bar character
like:

.B PATTERN1|PATTERN2|PATTERN3

The RegEx 'alternation' operator is sometimes more intuitive, because it tries
to match the provided patterns strictly in order from left to right. So it
would first try to match the first pattern, and only if no match with the first
pattern was possible (independent of string length) it would then try to match
the second pattern, and so on.

.SH "SEE ALSO"
.BR gig2mono(1),
.BR gigextract(1),
.BR gigdump(1),
.BR gigmerge(1)
.BR korg2gig(1)

.SH "BUGS"
Check and report bugs at http://bugs.linuxsampler.org
.SH "Author"
Application and manual page written by Christian Schoenebeck <cuse@users.sf.net>
1	schoenebeck	3995	.TH "wav2gig" "1" "03 Sep 2021" "libgig @VERSION@" "libgig tools"
2	schoenebeck	3980	.SH NAME
3			wav2gig \- Create GigaStudio (.gig) file from a set of WAV files.
4			.SH SYNOPSIS
5			.B wav2gig
6			[ OPTIONS ] GIG_FILE WAV_FILE_OR_DIR_1 [ WAV_FILE_OR_DIR_2 ... ]
7			.SH DESCRIPTION
8			Takes a list of wave (.wav) files and / or directories containing wave files as
9			argument(s) and creates one new GigaStudio / GigaSampler (.gig) file for those
10			samples.
11
12			The created GigaStudio (.gig) file will contain the given input samples. The
13	schoenebeck	3990	samples' meta information (as far as available) like root note
14			(a.k.a 'unity note'), fine tune, loop points, loop type and loop play count
15			are automatically extracted from the input wave (.wav) files and applied
16			accordingly.
17	schoenebeck	3980
18			Additionally this tool creates exactly one instrument inside the newly created
19			GigaStudio (.gig) file and tries to automatically map the samples in a
20			meaningful way to that instrument. As the wave (.wav) format currently does not
21			support many of the meta information required for this particular task, this
22	schoenebeck	3995	tool tries to extract the required (missing) information from the individual
23			sample's file name for being able to map the samples accordingly. See
24	schoenebeck	3980	.BR SAMPLE
25			.BR NAMES
26	schoenebeck	3990	below for details on the assumed naming scheme for input sample files and how
27			to override that default naming scheme by providing custom regular expression
28			patterns.
29	schoenebeck	3980
30			.SH OPTIONS
31			.TP
32			.B \ GIG_FILE
33			GigaStudio / GigaSampler (.gig) filename to be created
34			.TP
35			.B \ WAV_FILE_OR_DIR_1
36			Filename or directory containing wave (.wav) file(s)
37			.TP
38			.B \ WAV_FILE_OR_DIR_2
39			Filename or directory containing wave (.wav) file(s)
40			.TP
41			.B \ -r
42			Recurse through all subdirectories of provided input WAV directories.
43			.TP
44			.B \ -f
45			Overwrite output GigaStudio (.gig) file in case it already exists.
46			.TP
47			.B \ -v
48			Print version and exit.
49	schoenebeck	3990	.TP
50	schoenebeck	3991	.B \ --dry-run
51			Scan input sample (.wav) files, but exit before creating any .gig file.
52			.TP
53	schoenebeck	3992	.B \ --verbose
54			Increase amount of info being shown.
55			.TP
56	schoenebeck	3990	.B \ --regex-name1 PATTERN
57			Regular expression for overriding the
58			.BR NAME1
59			part of the input sample file name scheme.
60	schoenebeck	3980
61	schoenebeck	3994	Defaults to '([^-\/\\]+) - [^-]+ - [^-]+ - [^-]+ - [^.]+'.
62	schoenebeck	3990
63			.TP
64			.B \ --regex-name2 PATTERN
65			Regular expression for overriding the
66			.BR NAME2
67			part of the input sample file name scheme.
68
69	schoenebeck	3994	Defaults to '[^-\/\\]+ - ([^-]+) - [^-]+ - [^-]+ - [^.]+'.
70	schoenebeck	3990
71			.TP
72			.B \ --regex-velocity-nr PATTERN
73			Regular expression for overriding the
74			.BR VELOCITY_NR
75			part of the input sample file name scheme.
76
77	schoenebeck	3994	Defaults to '[^-\/\\]+ - [^-]+ - ([^-]+) - [^-]+ - [^.]+'.
78	schoenebeck	3990
79			.TP
80			.B \ --regex-note-nr PATTERN
81			Regular expression for overriding the
82			.BR NOTE_NR
83			part of the input sample file name scheme.
84
85	schoenebeck	3994	Defaults to '[^-\/\\]+ - [^-]+ - [^-]+ - ([^-]+) - [^.]+'.
86	schoenebeck	3990
87			.TP
88			.B \ --regex-note-name PATTERN
89			Regular expression for overriding the
90			.BR NOTE_NAME
91			part of the input sample file name scheme.
92
93	schoenebeck	3994	Defaults to '[^-\/\\]+ - [^-]+ - [^-]+ - [^-]+ - ([^.]+)'.
94	schoenebeck	3990
95	schoenebeck	3980	.SH SAMPLE NAMES
96	schoenebeck	3990	By default this tool assumes the following input sample file naming scheme for
97			automatically mapping samples to regions on the keyboard, as well as mapping
98			them to velocity splits adequately:
99	schoenebeck	3980
100	schoenebeck	3990	.B 'NAME1 - NAME2 - VELOCITY_NR - NOTE_NR - NOTE_NAME.wav'
101	schoenebeck	3980
102			Which are interpreted in the following way:
103
104			.TP
105			.B \ NAME1
106			Primary name of the sample (e.g. "Violin").
107
108			This is not interpreted for sample mapping, but it will be used to assemble the
109			final sample name inside the GigaStudio (.gig) file.
110
111	schoenebeck	3990	You may use
112			.BR --regex-name1
113			to override this part of the naming scheme.
114
115	schoenebeck	3980	.TP
116			.B \ NAME2
117			Secondary name of the sample (e.g. "Cresc").
118
119			This is currently ignored, but might be used in future.
120
121	schoenebeck	3990	You may use
122			.BR --regex-name2
123			to override this part of the naming scheme.
124
125	schoenebeck	3980	.TP
126			.B \ VELOCITY_NR
127			MIDI Velocity number of the sample (e.g. "18").
128
129			This informtion will be used to automatically create velocity splits.
130
131	schoenebeck	3990	You may use
132			.BR --regex-velocity-nr
133			to override this part of the naming scheme.
134
135	schoenebeck	3980	.TP
136			.B \ NOTE_NR
137			MIDI Note number of the sample (e.g. "021" for note a-1).
138
139			This informtion will be used to automatically map the sample to a region on the
140	schoenebeck	3994	keyboard. The sample's root note (a.k.a. "unity note") is taken directly from
141			the .wav file content, however if the .wav file content does not contain a root
142			note information then
143			.B \ NOTE_NR
144			is used as root note as well.
145	schoenebeck	3980
146	schoenebeck	3990	You may use
147			.BR --regex-note-nr
148			to override this part of the naming scheme.
149
150	schoenebeck	3980	.TP
151			.B \ NOTE_NAME
152			Note name of the sample (e.g. "a-1").
153
154			This is not interpreted for sample mapping, but it will be used to assemble the
155			final sample name inside the GigaStudio (.gig) file.
156
157	schoenebeck	3990	You may use
158			.BR --regex-note-name
159			to override this part of the naming scheme.
160
161	schoenebeck	3995	.PP
162			This tool utilizes the
163			.I regular expressions
164			library provided by C++ (introduced with the C++11 standard revision).
165			Each custom regular expression (abbreviated as 'RegEx' from now on below)
166			passed to one of the
167			.BR --regex-*
168			options must contain
169			.B
170			exactly one
171			active RegEx 'capture group' which is denoted in regular expressions by a pair
172			of round brackets like:
173
174			.B (PATTERN)
175
176			So the 'capture group' marks the portion in the overall filename string that is
177			going to be exctracted for the respective component of the filename schema.
178			If additional RegEx group(s) are needed to build the overall RegEx pattern, then
179			those other group(s) must be defined as 'passive groups' denoted in RegEx
180			patterns by an additional question mark and colon like this:
181
182			.B (?:PATTERN)
183
184			Keep in mind that RegEx scanners behave 'greedy' by default, which means by
185			default they try to match the longest string possible according to your defined
186			RegEx pattern. If that's not desired then you may either override the required
187			parts of your RegEx pattern to behave 'non-greedy' such that those parts would
188			match for the shortest string possible instead, or alternatively consider using
189			the RegEx 'alternation'
190			operator, which is denoted in regular expressions by a vertical bar character
191			like:
192
193			.B PATTERN1\|PATTERN2\|PATTERN3
194
195			The RegEx 'alternation' operator is sometimes more intuitive, because it tries
196			to match the provided patterns strictly in order from left to right. So it
197			would first try to match the first pattern, and only if no match with the first
198			pattern was possible (independent of string length) it would then try to match
199			the second pattern, and so on.
200
201	schoenebeck	3980	.SH "SEE ALSO"
202			.BR gig2mono(1),
203			.BR gigextract(1),
204			.BR gigdump(1),
205			.BR gigmerge(1)
206			.BR korg2gig(1)
207
208			.SH "BUGS"
209			Check and report bugs at http://bugs.linuxsampler.org
210			.SH "Author"
211			Application and manual page written by Christian Schoenebeck <cuse@users.sf.net>