# &app; Manual V&manrevision;

2004 Jean-Yves Lefort
&project; &documentation-license;
Jean-Yves Lefort
&project;

    jylefort@brutele.be

streamtuner Manual V&manrevision;
&date;

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.7
Saturday, October 23, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.6
Monday, August 9, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.5
Monday, July 26, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.4
Tuesday, May 11, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.3
Tuesday, May 11, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.2
Wednesday, March 31, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.1
Tuesday, March 30, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

streamtuner Manual V2.0
Tuesday, March 30, 2004

Jean-Yves Lefort jylefort@brutele.be

&project;

This manual describes version &appversion; of streamtuner.

Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, follow the directions in .

## Introduction

&app; is a stream directory browser. Through the use of a plugin system, it offers an intuitive >k; interface to Internet radio directories such as &shoutcast; and &live365;.

With &app;, you can:

- Browse the &shoutcast-yp;

- Browse the &live365; directory

- Browse the &xiph; directory

- Browse the &basic.ch; DJ mixes

- Manage your local music collection, with full support for ID3 and Vorbis metadata editing

- Listen to streams, browse their web page, or record them using programs such as Streamripper

- Implement new &handlers; as tiny &python; scripts or as dynamically loadable modules written in C

- Retain your favourite streams by bookmarking them

- Manually add streams to your collection

&app; offers hundreds of thousands of music resources in a fast and clean common interface.

### Terminology Side Note

Throughout &app; and this manual, media resources are referred to as streams.

However, because of the extensible nature of &app;, they really can be anything: an Internet audio stream, a MP3 or Ogg song, a web page, or even a television channel!

## Getting Started

### To Start &app;

You can start &app; in the following ways:

Applications menu

  Choose Multimedia &app; .

Command line

  To start &app; from a command line, type the following command, then press Return:

  `streamtuner` options

  where options is one or more options from the following list:

  --help

    Show help and exit

  --version

    Show version information and exit

  --directory directory

    Use configuration directory directory instead of the default `~/.streamtuner`

### When You Start &app;

When you start &app;, a window similar to the following one is displayed.

&app; Main Window

Shows &app; main window. Contains titlebar, menubar, toolbar, tabbed notebook and statusbar. Menubar contains Stream, Edit, View, Directories, and Help menus.

A few remarks:

- &Handlers; can be reordered by dragging their tab label.

- Right-clicking on the tab label of a &handler; will popup a menu presenting a couple of actions specific to that &handler;.

- Right-clicking on a stream column header will popup a menu allowing to hide the column or to show all columns.

- Right-clicking on a stream will popup a menu mostly similar to the Stream menu.

>k; Tips

Double-click on a column separator to autosize the column.

Drag a column header to move the column.

Press Ctrl S in a list to trigger the interactive search feature.

## Usage

You can use &app; to perform the following tasks:

- Browse a Stream Directory

- Search for Streams

- Tune Into Streams

- Record a Stream

- Browse the Web Page of a Stream

- Edit a Stream

- Delete Streams

- Add Bookmarks

- Create a Preselection

### To Browse a Stream Directory

To browse a stream directory, click on its tab and start navigating categories by selecting them.

Categories will be kept in the internal &app; cache and loaded from the network only if necessary, unless Always reload categories is enabled.

The number of available &handlers; depends on the loaded plugins.

### To Search for Streams

To search for streams in the current category, choose Edit Find .

Alternatively, you may use the >k; interactive search feature by pressing Ctrl S in a list.

To search for streams in all categories, choose Edit Search in All Categories .

Not all &handlers; support this feature.

### To Tune Into Streams

To tune into streams, select them and choose Stream Tune in (or press Return). You may also use the Tune in toolbar button, or the stream context menu (which can be accessed by right-clicking on a stream).

Some &handlers; can only tune into one stream at a time.

Properly Configuring Applications

You need to properly configure the applications needed to tune into streams. It can be done from the Applications tabbed section of the Preferences dialog.

### To Record a Stream

To record a stream, select it and choose Stream Record . You may also use the Record toolbar button, or the stream context menu (which can be accessed by right-clicking on a stream).

Properly Configuring Applications

You need to properly configure the applications needed to record streams. It can be done from the Applications tabbed section of the Preferences dialog.

### To Browse the Web Page of a Stream

To browse the web page of a stream, select it and choose Stream Browse (or, if the &handler; has no tune in feature, press Return). You may also use the Browse toolbar button, or the stream context menu (which can be accessed by right-clicking on a stream).

Properly Configuring Applications

You need to properly configure the applications needed to browse streams. It can be done from the Applications tabbed section of the Preferences dialog.

### To Edit a Stream

To edit a stream, select it and choose Stream Properties . You may also use the stream context menu (which can be accessed by right-clicking on a stream).

You will be presented with the Stream Properties dialog displaying the fields of the stream.

A field is editable only when it makes sense to do so. For example, you cannot edit SHOUTcast streams, since they are dynamic data loaded from the network.

### To Delete Streams

To delete streams, select them and choose Stream Delete . You may also use the stream context menu (which can be accessed by right-clicking on a stream).

If the &handler; requests it, you will be presented with a confirmation dialog.

Benign actions such as deleting bookmarks or preselections will not require confirmation.

### To Add Bookmarks

To add bookmarks, select one or more streams and choose Stream Add Bookmark . You may also use the stream context menu (which can be accessed by right-clicking on a stream).

The added bookmarks will show up in the Bookmarks tabbed section, and you will be able to edit their name, genre and description.

### To Create a Preselection

To create a preselection, choose Stream New Preselection .

You will be presented with the Stream Properties dialog, allowing you to edit the fields of the new preselection.

The Homepage field will be used to browse the preselection, and the URL field will be used to tune into the preselection.

## Plugins

&app; uses a plugin system to handle different stream directories, and ships with several plugins.

### SHOUTcast

This plugin provides an interface to the &shoutcast-yp;.

### Live365

This plugin adds &live365; support to &app;.

### Xiph

This plugin adds &xiph; support to &app;.

### Local

This plugin provides an interface to your local music collection. It can edit ID3 and Vorbis metadata.

Use the Music folder option to set the path to your music collection.

### Python

This plugin provides an embedded &python; interpreter, allowing to write &handlers; with the &python; programming language.

Three example scripts are shipped with the plugin:

- basic.ch.py, providing a &basic.ch; &handler;

- google-stations.py, providing a Google Stations &handler;

- punkcast.com.py, providing a punkcast.com &handler;

## Preferences

To configure &app;, choose Edit Preferences . The Preferences dialog contains the following pages:

- Applications

- General

- Network

- Plugins

  - Live365

  - SHOUTcast

  - punkcast.com

### Applications

These commands will be used to perform various actions.

The following percent substitutions will be applied:

%u

  Replaced by the &uri; to be acted upon

%q

  Replaced by the quoted &uri; to be acted upon

%%

  Replaced by a single percent character

Commands will not be run in a shell, so meta-characters and other shell specific features such as redirections will not be available.

### General

Show splash screen at startup

  If this option is enabled, a splash screen will be shown when starting &app;.

  On a fast system, keeping this option enabled is probably useless.

Always reload categories

  If this option is enabled, categories will be unconditionally reloaded when you select them. Otherwise, they will be looked up in the internal cache, reloading them only if needed.

Music folder:

  Use this option to set the path to your music collection (used by the Local plugin).

### Network

Use a proxy

  If this option is enabled and the Server field is filled, &app; will use a proxy server for data transfers.

  Otherwise, &libcurl; will use a proxy server if environment variables such as `http_proxy`, `ftp_proxy` or `all_proxy` are set.

  Type

    This option specifies the type of the proxy server to use.

    Socks 5 Support

    Some versions of &libcurl; are known to have problems with Socks 5 proxies.

  Server

    This field must contain the hostname or IP address of the proxy server to use.

  Port

    This field must contain the port number of the proxy server to use.

    Standard Port Numbers

    HTTP proxies commonly listen on port 8080 or 3120.

    Socks 5 proxies commonly listen on port 1080.

  Use proxy authentication

    You should enable this option if your proxy server requires user authentication.

    Name

      This field must contain your proxy login name.

      If it is left blank, you will be prompted for your login name when needed.

    Password

      This field must contain your proxy password.

      If it is left blank, you will be prompted for your password when needed.

      If the field is filled, the password will be stored in clear text in the `~/.streamtuner/config` file.

### Plugins

This page displays the list of plugins found at startup, and allows you to disable the plugins you do not need.

#### Live365

Streams Limit

  You can choose to limit the number of streams to download per category by enabling the Load at most option.

Membership

  If you are registered to &live365;, you might want to use your membership to tune into streams (some stations will only be available to paying members).

  You can use your membership by enabling the Use membership option and filling the Name and Password fields (if a field is left blank, you will be prompted for it when needed).

  If the password field is filled, the password will be stored in clear text in the `~/.streamtuner/config` file.

#### SHOUTcast

Streams Limit

  You can choose to limit the number of streams to download per category by enabling the Load at most option.

#### punkcast.com

Images

  You can choose to not download the show banners by disabling the Download images option.

## Technical Information

### Configuration Files

`~/.streamtuner/accels`

  The >k; accelerators file

`~/.streamtuner/cache`

  The cache directory

`~/.streamtuner/config`

  The configuration file

`~/.streamtuner/disabled-plugins`

  The list of disabled plugins

`~/.streamtuner/splash-disabled`

  If this file exists, the splash screen will not be displayed.

### Search Paths

Plugins will be looked up in `LIBDIR/streamtuner/plugins`, `~/.streamtuner/plugins`, and in the directories specified in the colon-separated environment variable `STREAMTUNER_PLUGINS_PATH` (in that order). Filenames not having the system-specific shared object extension (usually .so) will be ignored.

&python; scripts will be looked up in `LIBDIR/streamtuner/python/scripts` and `~/.streamtuner/python/scripts` (in that order). Filenames not having the .py extension will be ignored.

### Quality of Source Code

&app; is extremely stable. The source code is production-quality, and special care has been taken to ensure that the plugins will never trust their input.

## About &app;

&app; was written by Jean-Yves Lefort (jylefort@brutele.be). To find more information about &app;, visit the streamtuner web page.

### Reporting Bugs and Other Feedback

- Bug reports should be sent to streamtuner-bugs@nongnu.org.

- Questions, patches and various feedback should be sent to streamtuner-misc@nongnu.org.

### Acknowledgements

The following people have contributed code, packages, translations, money or have helped to fix bugs:

- Dan Allen

- Novák Áron

- Alban Bedel

- Wolfgang Meyer zu Bergsten

- Gonéri Le Bouder

- Elmar Hoffmann

- Ulrich Ivens

- Jose Jorge

- Rudolf Kastl

- Marc Lavallée

- Satoshi Machino

- Jeff Moe

- Adam Nevins

- Matthew Newton

- Andy Piper

- Marcus Rückert

- Kim Schulz

- Stephen Stackwick

- Martin Stromberger

- Philipp Thomas

### Licensing Terms

&software-license;

## Glossary

D

directory handler

  In &app; terminology, both the logic used to handle a music resource provider (such as an online stream directory or your local music collection), and the user interface element representing it (a tabbed section in the main notebook).

L

libcurl

  A multiprotocol file transfer library used by &app; for its data transfers. More information can be found on the libcurl web page.

S

session

  In &app; terminology, the application state (position, visibility and dimensions of user interface elements, preferences, contents of the cache, ...).

U

URI
Uniform Resource Identifier
URI

  A compact string of characters for identifying an abtract or physical resource, as defined by RFC 2396.

streamtuner