LineIn plugin for Winamp 2/5 Documentation - Option reference
Up | Previous | Next | Down
The beta version (v0.0) is extremely simple (just open the location: 'line://mic'), but for the newer versions it's a bit more complicated:
You can give parameters to the plugin by opening a certain URL, just line://
gets you the standard settings (44kHz, 16bps, stereo, 10 buffers of 3528 bytes).
Below is the list of current options (v1.0 and newer):
-
- srate=x
- Determines the samplerate (default: 44100)
Can be one of the following (v1.42 and earlier):
- 6000 (or 6) (v1.1)
- 8000 (or 8) (v1.0)
- 11025 (or 11) (v1.0)
- 16000 (or 16) (v1.1)
- 22050 (or 22) (v1.0)
- 32000 (or 32) (v1.1)
- 44100 (or 44) (v1.0)
- 48000 (or 48) (v1.1)
- 64000 (or 64) (v1.1)
Remember that your soundcard has to support the samplerate! Especially 64000 isn't supported much.
For versions later than v1.42 (from v1.50) you can enter any samplerate between 1 and 768000 Hz, of course your soundcard still has to support it.
From v1.50 the shorthands are not supported anymore.
bps=x
- Determines the number of bits per sample (default: 16)
Can be one of the following (v1.42 and earlier):
32 bit sound isn't supported by a lot of soundcards.
For versions later than v1.42 (from v1.50) you can enter any value between 1 and 64 (although you will be asked wether the plugin shall round the value up to the nearest multiple of eight if you don't enter a number that's a multiple of eight, also the internal blockalign field will always use the rounded up value). Of course your soundcard has to support it.
NOTE: My plugin supports 24bps sound from v1.50, but not every output plugin does, in my experience the waveOut and DirectSound plugins do not handle it correctly. The DiskWriter plugin does handle it correctly though, as do my own Low-Latency waveOut output plugin and File Writer output plugin.
nch=x
- Determines wether the device is mono or stereo (default: 2)
Can be one of the following:
For versions later than v1.42 (from v1.50) you can enter any value between 1 and 32, again your soundcard has to support it.
mono (v1.42)
- Same as nch=1
This parameter is like a flag.
stereo (v1.51)
- Same as nch=2
This parameter is like a flag.
time=x (was changed in v1.30)
- Specifies for how long the plugin should play (default: -, for ever)
If it's not specified the plugin will play for ever, it it's specified it will play for as long as specified.
Can be in the following form:
- v1.0 upto v1.23:
-
- h:m:s[.hs]
- for example: 2:30:5 will play for 2 hours, 30 minutes and 5 seconds
- m:s[.hs]
- for example: 2:30 will play for 2 and a half minutes
- The previous two can be extended with .hs (for example 1:20.50 will play for 1 minute, 20 seconds and 50 hundreds of a second).
- s.hs
- seconds.hundredsofseconds, so not just seconds, the plugin will interpret that as ms.
- ms
- for example: 1200 will play for 1200 milliseconds (1.2 seconds)
- v1.30 and up:
-
- h:m:s[.x]
- for example: 2:30:5 will play for 2 hours, 30 minutes and 5 seconds
- m:s[.x]
- for example: 2:30 will play for 2 and a half minutes
- s[.x]
- for example: 1200 will play for 1200 seconds (20 minutes)
- They can all be extended with .x, which is interpreted as fractions of seconds. x will be rounded to milliseconds.
For example 1:20.5 will play for 1 minute, 20 seconds and 500 milliseconds, half a second).
5.0025 will be rounded to 5.003 and 5.0024 will be rounded to 5.002
This format boils down to: [[h:]m:]s[.x]
notime (v1.70)
- A flag to counter the effect of any previous time options. Usefull for use with presets.
Same as time=-
stime=x (v1.41, changed in v1.80, see the NOTE)
- Starting time, when you use this the plugin will pause until it's the time you specified.
The format of the time is: h:m[[:s].x] (default: -, not set).
Example: line://stime=14:07,time=55:0,title=My favourite show!
Suppose it's 11:00 and you set this to play, the plugin will pause until it's 7 past 2 PM and then play for 55 minutes.
NOTE: From v1.80 this also uses the [[h:]m:]s[.x] syntax. I might change this later on.
nostime (v1.70)
- A flag to counter the effect of any previous stime options. Usefull for use with presets.
Same as stime=-
sdate=x (v1.50)
- Starting date, when you use this the plugin will pause until it's the date you specified.
The format of the date is: yyyy-m-d (default: -, not set, starting time will default to current time).
Example: line://sdate=2001-11-05,stime=20:07,time=55:0,title=That radio program I always wanted to hear!
Suppose it's November 4th, 2001 and you set this to play, the plugin will pause until it's 7 past 8 PM the next day and then play for 55 minutes.
nosdate (v1.70)
- A flag to counter the effect of any previous sdate options. Usefull for use with presets.
Same as sdate=-
numbuffers=x (v1.23, changed in v1.42 and again in v1.50)
- The number of buffers used. The plugin uses multiple buffers to reduce skipping and so on.
Has to be >=1 and <=1000 (default: 10, in versions previous to v1.42 the maximum used to be 50 and v1.42 has a maximum of 100).
Recommended not to set this to 1, this will probably result in enormous skips. Recommended is a setting of 10 or higher, but on a fast PC or if it's all you're running, less can decrease memory usage.
bufsize=x (v1.23, was changed in v1.50)
-
- v1.23 upto v1.42:
- The size of the buffers used (in bytes). You can specify it to suit your needs.
Has to be >=576 and <=8192 (default: 3528).
A lower setting is better for VIS, a higher setting improves performance and prevents skips. So if you want to do realtime VIS shows, use 576 (if you can).
- v1.50 and up:
bufsize=[t|s]x
The size of the buffers used in bytes (only value, x), time ('t' plus value, tx) or samples ('s' plus value, sx). You can specify it to suit your needs.
Has to be >=16 and <=1048576 for bytes and samples or >=1ms and <=10000ms (10 seconds), in the same format as the time option , for time (default: 1152 samples, in versions before v1.70 it used to be 4608 bytes, which is the same for the default options).
Example (bytes): bufsize=2304
creates a buffer of 2304 bytes
Example (samples): bufsize=s576
creates a buffer of 576 samples, which equals 2304 bytes at 16bps, Stereo
Example (time): bufsize=t0.012
creates a buffer with a duration of 0.012 seconds, which equals 576 samples or 2304 bytes at 48000Hz, 16bps, Stereo
A lower setting is better for VIS, a higher setting improves performance and prevents skips. So if you want to do realtime VIS shows, use s576 (if you can).
NOTE: Previous to v1.50 I made a wrong assumption about the optimal VIS value, it should have been 576 samples instead of bytes, which is usually 2304 bytes. Therefor it is recommended to use s576 instead of 576 with v1.50 and up of my plugin.
title=x (v1.30, changed in v1.80)
- Specifies the title to show instead of Line-In. This does not replace the (44100 Hz 16bps Stereo, buffers: 10x3528 bytes) part. To disable that use 'hideformat'.
Default is 'Line-In'.
This parameter can be very simple, just a name, like: My favourite channel
NOTE: The following is true for the old expand system (before v1.80, as well as the old expand system versions). Skip this part for v1.80 and up.
- But it also has support for more advanced parameters. You can use the backslash (\) to quote a ',' (otherwise it's seen as a parameter seperator). Also you can include variables in your title like the samplerate and so on.
For example:
line://title=My favourite channel\, in %ct!,hideformat
Gives (as a title)
- My favourite channel, in Stereo!
DO NOT forget to quote the ','!
Some examples:
line://title=My radio\, with a samplerate of %srHz
My radio, with a samplerate of 44100Hz (44100Hz 16bps Stereo, buffers: 10x3528)
line://title=My radio\, with a samplerate of %srHz,srate=8000,hideformat
My radio, with a samplerate of 8000Hz
Full list of variables (not all were implemented in v1.30):
- %sr - samplerate in Hz
%br - bitrate in KBps
%cn - number of channels (1 or 2)
%ct - number of channels (Mono or Stereo, or x channels for more than two channels in versions later than v1.42)
%bi - bits per sample
%ln - length in ms
%lt - length in the format: [[h:]m:]s[.x] (see the time parameter)
%bn - number of buffers
%bs - buffersize
%th - current time in hours
%tm - current time in hours and minutes
%ts - current time in hours, minutes and seconds (these options all use your own windows settings)
%tl - current time in milliseconds (this uses the same format as %lt)
%dl - current date, long format
%ds - current date, short format (these options use your own windows settings)
%st - starting time (same format as %ts)
%sd - starting date (same format as %ds)
%mu - muted (nothing if not muted)
%mt - muted (unmuted if not muted)
%ob - outbuflen (in ms)
%op - outprebuflen (in ms)
%ot - outbuflen (in time format, [[h:]m:]s[.x])
%ou - outprebuflen (in time format, [[h:]m:]s[.x])
%ck - wether the plugin performs the format checks (see the nochecks option) ('checks' or 'no checks')
%di - the device ID (corresponds to the dev option)
%dn - the device name (corresponds to the dev option)
%xNN - inserts a char with ASCII code NN (hex), for example %x20 for a space, or %x07 for a bell (don't know why you'd want that, but it's possible)
NOTE: The %sr, %br, %cn, %ct, %bi, %th, %tm, %ts, %tl, %dl, %ds, %ob, %op, %ot, %ou and %xNN variables also work with my File Writer output plugin.
NOTE: The following is only true for v1.80 and up:
- The title is a string, like this:
line://title=Just some string
And you can use variables and commands inside that string, like this:
line://title=This uses ${nch} channels#if(${ismuted};==;true;\, and is muted;)
The only way to quote something (escape something) is to use a backslash, although the backslash used in this example will be removed in the process of parsing the commands, not while expanding the title (the comma has no special meaning in the title, so it doesn't need to be escaped for the expand step, if it did it would have to be escaped with three backslashes). Also nested commands are escaped, you don't have to do: #if(#if(a\;==\;b;;);==
... , but you do have to do: #if(a semicolon like this one '\;';==;a semicolon like this one '\;';
...
Variables are specified like this: ${varname}
or ${varname(withparametershere[;optionallymorethanoneparameter])}
Commands like this: #commandname(parameter[;anotherparameter])
The second example just above would result in:
Or if muted was specified (or ismuted=true
, or ismuted=yes
):
- This uses 2 channels, and is muted
Variable types
Each variable is of a certain type, most are of the numeric or text type. The type influences the way a value is output and what kind of input it allows. The following types exist (at the moment, there will probably be others in the future):
-
- Text
- The text type is nothing more than a simple string, it takes a string as input and it literally outputs the same string.
- Numeric
- The numeric type holds a number, so anything you give it will be converted to a number and then back to a string when it's shown again. Example:
line://title=I'm using ${numbuffers} buffers,numbuffers=034
Will become:
- Boolean
- The boolean type holds a boolean, a variable than can only be true or false. This type normally outputs 'true' or 'false' when used in the title, but in some cases it might output something else (if there is a good reason for it). The variable will however accept both true/false and yes/no, so ismuted=true is equivalent to ismuted=yes.
- Time
- The time type holds a time, it takes the [[h:]m:]s[.x] syntax as input and outputs in almost the same format (h:m:s[.x], for easy file sorting and such). In the future I will give it a parameter so you can specify the format in which to output the time.
- Date
- The date type holds a date, the syntax for both input and output is yyyy-mm-dd (input doesn't need leading zeroes though). A parameter for specifying the format will be added in the future.
Variables
Each variable can be accessed using ${varname}
, so if you want the number of channels used you specify ${nch}
, if you want the device string you specified you use ${dev}
. The names of options correspond to the variables, only presets are handled specially, as well as "flags" (like mute and checks), there is no way to get the name of any presets used through variables and flags are mapped to non-flag options:
mute
becomes ismuted=true
unmute
becomes ismuted=false
showformat
becomes showformat=true
hideformat
becomes showformat=false
mono
becomes nch=1
stereo
becomes nch=2
notime
becomes time=-
nostime
becomes stime=-
nosdate
becomes sdate=-
mute
becomes ismuted=true
unmute
becomes ismuted=false
checks
becomes performchecks=yes
nochecks
becomes performchecks=no
nochnmap
becomes chnmap=
(nothing)
The variables you can use are the following options (I've put the types behind the names):
srate
(numeric)
bps
(numeric)
nch
(numeric)
time
(time)
stime
(time)
sdate
(date)
numbuffers
(numeric)
bufsize
(text, because of the flags, is probably going to change in the future)
title
(text)
showformat
(boolean)
dev
(text, same story as with bufsize)
ismuted
(boolean)
outbuflen
(time)
outprebuflen
(time)
performchecks
(boolean)
chnmap
(text, more or less the same story as with dev and bufsize)
As well as these special variables (a lot of which are going to be replaced by, for example, adding parameters to existing variables), they are all text variables:
bitrate
(in kbps, kilobytes per second)
bufsize-bytes
(the buffersize in bytes)
dev-name
(the name of the device used)
dev-id
(the id of the device used)
dev-type
(the type of the device used)
curtime-h
(current time; just the hour)
curtime-hm
(current time; hours and minutes)
curtime-hms
(current time; hours, minutes and seconds)
curtime-long
(current time; hours, minutes, seconds and milliseconds)
At this moment not everything that used to be possible is possible with the new scheme, therefor I am offering two versions for download, one with the old expander and one with the new one. If you don't need the old options you should use the new expander, as I will remove the old functionality when it becomes entirely obsolete.
BTW, ascii codes can be inserted using %##, where ## is a hexidecimal number (e.g. %20 will insert a space).
Commands
Entirely new is the possibility to use commands in the title, most commands do something to the string you feed them, like trimming it or making it uppercase or lowercase. The following is a list of commands you can use:
-
- #abbr(stringtoabbreviate[;minsizetoabbreviate])
- Abbreviates a string (takes the first letter of every word), but only if stringtoabbreviate is longer than minsizetoabbreviate.
- #bpad(stringtopad;numberofcharstopadto;padchar)
- Adds chars to the back of the string.
- #btrunc(stringtotruncate;numcharstotruncateto[;truncendstring])
- Truncates a string (from the back, similar to right$ in basic), so '#btrunc(hello world!,8,...)' becomes '...orld!'.
- #fpad(stringtopad;numberofcharstopadto;padchar)
- Adds chars to the front of the string (see #bpad).
- #ftrunc(stringtotruncate;numcharstotruncateto[;truncendstring])
- Truncates a string (from the front) (see #btrunc).
- #if(expandablestring;truepart;falsepart)
- Checks wether all the vars in expandablestring exist.
- #if(operand1;operator;operand2;truepart;falsepart)
- Performs the requested comparison, for example: #if(2,>!,3,Two is greater than three.,Two is smaller than\\, or equal to\\, three.) returns: Two is smaller than, or equal to, three.
The operator can be: ==, >=, <=, !=, > or < , and each one of those can be optionally be appended with a ! or @, the ! meaning the operands should be converted to numbers before comparing (#if(02;>;1;yeah!;strange) will return strange, but #if(02;>!;yeah!;strange) will return yeah!), and the @ specifies that the comparison should be "textual", the way a dictionary is sorted (unfortunately this doesn't work yet).
- #knownvars(stringwithvars)
- Returns the number of known vars in stringwithvars.
- #lower(stringtolow)
- Makes a string lowercase. (doesn't work on characters like é or ä yet)
- #ltrim(stringtotrim;charstotrim)
- Trims a string. Removes characters from stringtotrime from the front until it encounters one that isn't in charstotrim. E.g. #ltrim( _hello_this is a holiday; _) will return 'hello_this is a holiday'.
- #numvars(stringwithvars)
- Returns the number of vars in the string.
- #rtrim(stringtotrim;charstotrim)
- Trims a string from the back. See #ltrim.
- #trim(stringtotrim;charstotrim)
- Trims a string from both sides. See #ltrim.
- #unknownvars(stringwithvars)
- Returns the number of unknown vars in the string.
- #upper(stringtoup)
- Makes a string uppercase. (doesn't work on characters like é or ä yet)
If there are any other things you would like to see added to this list (these lists), just mail me.
hideformat (v1.30)
- Hides the part of the name that specifies the format used. This is meant to be used together with title, but also for those of you who just don't like to see the format.
The default is: not set. This is not a parameter which takes a value. It's more like a flag.
Same as showformat=false
showformat (v1.51)
- Shows the part of the name that specifies the format used. This is meant to be used to undo hideformat (which you might have set in a preset.
The default is: set. This is not a parameter which takes a value. It's more like a flag.
Same as showformat=true
showformat=x (v1.80)
- Determines wether to show the part of the name that specifies the format used.
The default is: true.
This is a boolean and thus accepts true, false, yes or no.
dev=x (v1.40)
- The device to use.
- v1.40 upto v1.51:
- The device ID.
For the list of possible numbers, see the config box. (default: -1, the wave mapper)
This is NOT a replacement for windows volume control, this is meant to make it possible to use things like a Virtual Audio Cable.
NOTE: Versions older than 1.40 of my plugin used device 0 instead of -1.
This means that if you didn't have sound at all with an older version of my plugin, and you've got more than one sounddevice (two soundcards or one soundcard and for example Virtual Audio Cable), this might solve your problem.
- v1.60 and up:
- One of the following:
dev=x
x is the device ID, just like with the old version of this parameter
dev=wx
x is a device alias for a standard device (I use w because of the names of the API calls)
dev=dx
x is a device alias for a DirectSound device (d for DirectSound)
mute (v1.41)
- This will mute the sound, that means that the plugin won't output anything (actually just zeros). The VIS and DSP are fed with data however.
The default is: not set. This is like a flag.
Same as ismuted=true
unmute (v1.51)
- This will unmute the sound, this is to undo the effects of the mute option (which might have been set in a preset).
The default is: set. This is like a flag.
Same as ismuted=false
ismuted=x (v1.80)
- This determines wether the sound will be muted.
The default is: false.
outbuflen=x (v1.42)
- The output buffer length in ms (format: h:m[[:s].x]).
The default is: - (specify 0 for the default value of the output plugin)
From v1.51 you can also specify - (a minus sign) as a value, this will counter the effect of a previous outbuflen option (which might have been inside a preset). It will also set the outprebuflen option back to -1.
This option is meant for tweaking purposes, it should set the output plugin's buffer size, but my plugin can't garantee that it does (the output plugin has to implement it).
NOTE: This value should be higher than or equal to outprebuflen.
outprebuflen=x (v1.42)
- The output prebuffer length in ms (format: h:m[[:s].x]).
The default is: - (specify 0 for the default value of the output plugin)
From v1.51 you can also specify - (a minus sign) as a value, this will counter the effect of a previous outprebuflen option (which might have been inside a preset). This will not set the outbuflen option back to -1.
This option is meant for tweaking purposes, it should set the output plugin's prebuffer size, but my plugin can't garantee that it does (the output plugin has to implement it).
NOTE: This value should be lower than or equal to outbuflen.
nochecks (v1.50)
- A flag to disable the format checks (means you won't get any messages telling you that your buffer size could crash Winamp or that your bits per sample is not a multiple of eight), can be usefull if you have a setup that supports 20bit sound or want to use a very small buffer size.
Default: not set.
Same as performchecks=false
checks (v1.51)
- A flag to counter the effect of a previous nochecks option (which might have been set in a preset).
Default: set.
Same as performchecks=true
performchecks=x (v1.80)
- A flag to specify wether or not to perform format checks (see nochecks), can be usefull if you have a setup that supports 20bit sound or want to use a very small buffer size.
Default: true.
preset=x (v1.50)
- This lets you use a preset, for example you could create a preset (see the Customizing section) called radio that would contain the following:
srate=32000,mono,title=My radio,hideformat
After you've created the preset the following two would be equivalent:
line://srate=32000,mono,title=My radio,hideformat
line://preset=radio
Of which the second one would be a lot easier to type than the first.
Default: not used.
NOTE 1: When you create a preset you can use the preset option within the preset, but you should use this option with care, if you create a loop, the plugin will hang! (only in v1.50, v1.51 will automatically stop processing the parameters)
NOTE 2: The preset option MUST be the first option specified, otherwise it won't be recognised. From v1.51 you can specify a preset option after another preset option, which would look like this (for example):
line://preset=somepreset,preset=anotherpreset,preset=thirdpreset,srate=32000
From v1.70 you can use presets anywhere in the option string, like this:
line://nch=1,bps=24,preset=somepreset,preset=anotherpreset,dev=wtape,preset=thirdpreset,srate=32000
You can specify more options after the preset option, this allows you to make one general preset that specifies certain things and then customize it a little when you use it, for example you might have created a preset called 'vis' containing: srate=48000,bufsize=s576,title=Good VIS
.
Now you want to use that preset with a 96000 Hz source, all you have to do is this:
line://preset=vis,srate=96000
chnmap=x (v1.71)
- This allows you to set a channel map by specifying which input channels map to which output channels (or actually the other way around). Any channel mapping is performed BEFORE the sound is passed on to Winamp (this includes the DSP plugin, VIS plugin and output plugin).
Default: not set (nothing).
Examples:
line://chnmap=01
Has no (audible) effect, it maps channel 0 to channel 0, and channel 1 to channel 1
line://chnmap=10
Swaps the channels, left becomes right and right becomes left
line://chnmap=-1
Mutes the left channel (channel 0)
line://chnmap=0-
Mutes the right channel (channel 1)
line://chnmap=-0
Mutes the right channel (channel 1) and swaps the channels (you will hear the left channel through the right speaker and no sound from the left speaker).
line://chnmap=11
Puts the right channel in both channels.
line://nch=4,chnmap=2310
Output channel 0 would get the sound from input channel 2, output channel 1 from input channel 3, output channel 2 from input channel 1 and output channel 3 from input channel 0.
Please note that using the chnmap option will slow down the plugin a bit (wether you will notice it or not depends on your hardware), even if you use something like chnmap=01.
nochnmap (v1.71)
- A flag to counter the effect of a previous chnmap option (which might have been set in a preset).
Default: set.
Same as chnmap= (nothing)
Up | Previous | Next | Down
To contact me, please mail to: th.v.d.gronde@hccnet.nl
I hope you'll enjoy my program(s).