Back to files

----------- Trout 0.3.0rc1 -----------

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.

The GNU GPL should be distributed with the Trout package as the file COPYING.

---

Warning - beta software!

This software is still in a early development stage, and comes with no warranty, so use at your own risk. Keep regular backups of data on your system, as it is perfectly possible running Trout could irreversibly damage your system and generally do bad things. Please still test out this software and email the author if you find any bugs.

Only stream music that you have permission from the copyright holder to stream, don't do anything illegal with Trout. In the case of personal injury due to use of Trout, the creators of Trout accept no responsibility or liability. This includes, but is not restricted to, physical damage, loss of job, loss of sleep, loss of data, trouble with the law, painful bowel infections and loss of money.

Contents

Usage
Settings
2.1 Config File 2.2 Command line options
FAQ
Known Bugs
Contact info and Credits

1. Usage

Put simply to get Trout working do the following:

Create a text file named trout.m3u in your home directory as the user you will run Trout as. List all the mp3s on your pc you want to stream, with a new line for each one and with no escape characters. For example: /home/usera/mp3s/Great Song - Great Band.mp3 ~/mp3s/Farfetched - 01 - keep it simple
Run Trout with ./trout.pl
Connect to port 8000 with a mp3 player and listen.

Trout can fail on running if the directory containing the Trout subdirectory (where all the modules are stored) is not included in the @INC array for Perl. This means you need to be in the directory which contains the Trout subdirectory.

It is also possible to install trout so any user can access it by doing the standard Perl thing:

perl Makefile.pl
make
make test
make install

You can leave out test, but it will tell you if there will be problems with your system.

----------- 2. Settings -----------

2.1 Config file setup

Trout will attempt to read the config from ~/.trout and then any config file specified on the command line (see section 2.2). At the moment Trout is very picky when it comes to reading the config file. Anything between a # and a newline (for your system) will be ignored. 1 space is allowed either side of the =, but any others will be interpreted as being part of the option or value. All take the form of:

Option = Value

One important point to note is that the config file is case sensitive, so make sure you have all of the case correct (note that many options have capitalised letters in the middle)

Valid items:

ServerName=String

Fairly obvious this one, it sets the name the server reports itself as to clients. If specified as a command line option remember to put "quotes" round the name. Names have all characters removed from them which are not A to Z, a to z, 0 to 9, space, _ (underscore), - (dash), . (fullstop) or , (comma).
---

LogFile=./trout.log

Where the log should be logged to, relative to where Trout was started. If this is not defined or blank, no logfile will be used.

LogLevels=
WarnLevels=

These two are special, they need a comma separated list after them of the following:

Network # Says when Clients connect and drop NetworkD # Says IP and port of clients (needs above option) Local # Says General Errors on opening files (You want this one) LocalD # Says When it goes to open files. Debug # Says EVERYTHING

Each one must be preceded by a + or a -. If these are preceded by a - then they will be disabled. And those preceded by a + will be enabled. By default Trout acts as if it was told: WarnLevels=+Network,+Local

This means that if you want disable one of these you have to say: WarnLevels=-Network,-Local

Trout checks first for options switched on, then for options switched off. This means that:

WarnLevels=+Network,-Network,-Local,+Local

Will be treated like:

WarnLevels=-Network,-Local

MakePlaylist=1

If set to 1 then Trout will attempt to create a playlist to file by searching SearchPath (see next config file option) for supported files, which is currently *.mp1, *.mp2, *.mp3. ---

SeachPath=%h;/mnt/mp3player;/path/with/semicolon%s

This tells Trout which directories to search for supported files in if MakePlaylist enabled. They should be in a semicolon separated list. The following 'escape' characters are possible: %h = the home directory of the user Trout is run as. %% = a % character.
%s = a semicolon.
---

Playlist=./playlist.m3u

Use this option to specify where Trout should load/create the playlist from/to, relative to the path Trout is run from. Be careful that you have set MakePlaylist correctly - if it is set to 1 then the file given will be overwritten.
---

ServerPort=8000

The TCP port that the server will listen for connections on. Make sure the user running Trout can open this port, and that its not in use by another program (Port 8000 is a common port for streaming).

Ports can in theory be anything up to 65536, but you should not use a number lower than 1024 (which are reserved for standard protocols), or higher than 32768 (which are used for outgoing ports). If you can't use 8000 the best thing to go for is normally 8001, 8002 etc. ---

PlayMode=0

Sets the order in which files are played. 0 (zero as in (2*4)-8) is in random order, 1 is in playlist order, 2 in the playlist order but start at a random point in the playlist, 3 is randomize the playlist and then go through one by one.
---

Downsample=0

Tells Trout if it should pass files through the command specified with MP3encoder.
---

MP3encoder=/usr/bin/lame
MP3encoderOptions=-b 32 --mp3input %f -

If Downsample=1 is set then Trout will use the command specified by MP3encoder= with the options specified to it by MP3encoderOptions= as the command line options. Each option is treated as being separated by spaces, so instead of quoting things like on a shell, %s needs to be used instead of space. "option 1 is on" would become option%s1%sis%son. Trout will replace %f with the file to be downsampled, so its a good idea to include it. :) If a % is needed %% will be changed to a %.
---

MTU=24576

Sets the number of bytes to attempt to send each time a socket is able to be written to, too large and Trout will be slow and use lots of memory, too small and Trout will have to attempt to write to the socket repetitively, using up CPU time. Most systems can leave this out, as the default of 24KB seems to work well, but feel free to try to tweak performance with this.
---

Readahead=24576

The amount of the input (in bytes) that Trout tries to read in from the input. If this is too small then Trout will increase CPU usage as it has to read in repetitively from the input, too large and Trout uses up more cpu and memory as it shifts a large amount of data around in memory. Default of 24KB works well on most machines. ---

MaxConnections=-1

The maximum number of connections Trout should stream to at one time. Set this to -1 to have unlimited connections, and a non integer for some funky fun.
---

DropPoint=64000

Sets the number of bytes a connection has to be off the end of the buffer before being dropped. If a connection is off the end of the buffer, but still not past the drop off point, it will get jumped into the middle of the buffer and a log message about artificial advancement will be given at level NetworkD. You shouldn't really need to fiddle around with this option, but you might want to change it off the default of 64KB.
---

Buffer=192000

Sets the size, in bytes, of the buffer for outgoing data. 192KB seems to be work well, so you probably won't want to change this. Its best to keep this at more than double what you would expect a typical client to buffer at the client side.

2.2 Command line options

run ./trout.pl --help for the command line options.

3 FAQ

Ok, so I've never been asked asked a single question about Trout, but always wanted to write an FAQ, and I needed somewhere to stick bits of information.

3.1 Why Trout?
3.2 Is Trout secure?
3.3 I keep getting dropped, or the stream jumps

3.1 Why Trout?

Trout is called Trout for 2 reasons. Trouts swim in rivers, which are like streams, and it streams music. And also TROUT stands for:

To
Rock
On
Use
Trout

We did consider using Audio Relay Server Environment (thanks to Tom Gray for that suggestion), but decided it was not suitable ;-)

3.2 Is Trout secure?

As far as I know, yes :). Trout will only stream data which contains a valid MPEG audio frame header, or ID3v2 tags. This makes it difficult to get Trout to stream data which is not MPEG audio data, with out having write on the files that Trout will try to stream.

Any bugs in Perl's network sockets read and writes will cause Trout to be insecure, but if Perl is discovered to have any, it's not the fault of Trout.

Trout does not perform locking on files, but Trout will just skip to the next file if it has problems with the current file, so this shouldn't be a problem. The biggest problem this could cause is ruining the log file or the playlist while its created.

3.3 I keep getting dropped, or the stream jumps

Play the audio file that the problems occurred on, without using Trout. If it sounds the same, don't blame Trout, blame your audio player. If it sounds fine then its a problem in Trout's timing routine. If this does happen email me (siax@users.sourceforge.net) but DO NOT SEND THE FILE AS AN ATTACHMENT. I SAID DO NOT SEND THE FILE AS AN ATTACHMENT. In case you didn't hear me DO NOT SEND ME ANY ATTACHMENTS. If possible find out the bitrate of the file, the sampling rate, the version and the layer of the file. If the previous sentence means nothing, still email me, I'm sure we can work something out.

Just remember I do not want your stinkin' audio files emailed to me :)

4 Known Bugs

Trout will exit with errors if your machine has no concept of a home directory. This includes is known to include Perl on Win 9x, but might affect other operating systems.
And probably lots more...

5 Contact info and Credits

Trout was initially started by Alan Woodland.

The QT/KDE frontend was then created by James Thorniley, originally under the name KStream, but now KCast.

The document on reading MPEG audio headers at: http://www.dv.co.yu/mpgscript/mpeghdr.htm by Predrag Supurovic was invaluable in the creation of Trout.

Direct your questions about Trout to:
Toby Gray (siax@users.sourceforge.net)

Direct questions about KCast to:
James Thorniley (hammy@users.sourceforge.net)

And email either of us if you just feel lonely and want a chat.

Get the latest version of Trout/KCast at: http://kcast.sourceforge.net

FIN