NeTraverse Network Audio (Version 1)
Win4Lin Audio Plugin HOWTO
====================================

SCOPE
=====
This document will explain how to use the nnaudio plugin for Win4Lin to enable
remote sound to nnaudio-compatbile audio servers.  This document assumes that
a remote nnaudio server is configured and properly listening for connections,
and that any network/routing issues from the Win4Lin computer to the sound
server have been resolved.

ABOUT NNAUDIO
=============
NeTraverse Network Audio (nnaudio) is a remote audio protocol designed
specifically for higher bandwidth LAN-type connectivity.  It is ideally suited
for use in a local Ethernet network of thin clients/X terminals.  It was 
originally designed for enabling remote sound from Win4Lin on SunRay clients 
(from Sun Microsystems), but is generic enough to present a solid remote sound 
solution on any platform.  The protocol itself is fully documented later in 
this file.  What makes nnaudio unique is that it provides a method to
synchronize audio playback to real time.  This allows Win4Lin to better
play multimedia files remotely.

The nnaudio protocol also provides versioning.  This will allow the protocol
to evolve over time, adding new features such as Mixer control and audio
recording.  In version 1 of the protocol, only audio playback is supported.

INSTALLING THE PLUGIN
=====================
You can expect the nnaudio plugin to be part of the Win4Lin RPM in the near
future.  Until that time, it can be installed on Win4Lin 4.0.5/Win4Lin Terminal
Server 2.0.5 or higher (Win4Lin-5.3.5e*.rpm) or higher by downloading the
libnnaudioplugin.so file and placing it in the /opt/win4lin directory.  The
file should be given 555 permissions, and should be owned by root.  If a file
by that name already exists in that directory, this means that you are using
a newer version of Win4Lin that ships with this plugin already.  Do not replace
the one that is already there if this is the case.

USING THE PLUGIN
================
There are two ways to use the plugin.  The first way is by setting the
appropriate environment variables before launching 'win' as a non-root user:

	$ export MERGE_AUDIO_PLUGIN=/opt/win4lin/libnnaudioplugin.so
	$ win &

This will launch a Win4Lin session that will attempt to play sound remotely
on an nnaudio server.  By default, the plugin determines which nnaudio server
to use by the host specified in the ${DISPLAY} environment variable.  This
default is perfectly fine if you are using a normal remote X server, such as
in LTSP setups or SunRay setups.  If your display mechanism is not X11, it is
likely that the ${DISPLAY} variable is set to an address on the local host,
such as when using VNC.  In this case, the ${NNAUDIOHOST} variable can be set:

	$ export MERGE_AUDIO_PLUGIN=/opt/win4lin/libnnaudioplugin.so
	$ export NNAUDIOHOST=192.168.1.15:0
	$ win &

The ${NNAUDIOHOST} variable can also specify a port number if the default
TCP/IP port of 48601 is not valid for your setup:

	$ export NNAUDIOHOST=192.168.1.15:12345

Also, /etc/services should be appended to define the 'nnaudio' service with
the following line:

	nnaudio		48601/tcp		# nnaudio port

The number 48601 can be replaced with whatever is appropriate for your
network.  Contact your network administrator if you are unsure.

The other method of enabling the nnaudio plugin is by changing the
MERGE_AUDIO_PLUGIN setting in /etc/default/merge.  Simply change it to the
following:

	MERGE_AUDIO_PLUGIN="/opt/win4lin/libnnaudioplugin.so"

Note that this change becomes the global default.  This method should be used
if most of the terminals on your network support nnaudio.  You can then of
course override it on a user-by-user basis by setting the
${MERGE_AUDIO_PLUGIN} variable to load a different plugin before running 'win'.

THE NNAUDIO PROTOCOL
====================
If you intend to develop your own nnaudio compliant client or server, you can
simply extract the nnaudio.h C header file from this document as indicated
below.  You will find the protocol flow and all the associate data structures
defined directly in the header file.  The underlying transport protocol for 
nnaudio is TCP/IP.


------nnaudio.h: cut here------

/*
**	nnaudio.h:
**		NeTraverse Network Audio
**		Protocol header file
**
**	Copyright (C) 2002 NeTraverse, Inc.
**	All Rights Reserved.
**
*/
#ifndef NNAUDIO_H_INCLUDED
#define NNAUDIO_H_INCLUDED

#define NNAUDIO_VERSION		1		/* protocol version	*/
#define NNAUDIO_PORT_DEFAULT	48601		/* default tcp port	*/

/*
**	Protocol flow (version 1):
**
**		client->connect()
**		client->send protocol version (unsigned short)
**		server->send response code (unsigned char) to protocol version
**		client->send 128 bytes of arbitrary connection data
**		server->send NNAUDIO_PKT_CAPS
**		client->send NNAUDIO_PKT_PROGRAM
**		server->send response code to (unsigned char) to program
**		client->send NNAUDIO_PKT_AUDIO
**		server->send NNAUDIO_CTL_ACK
**
**	NOTES:
**		1. all numeric data is in network byte order
**		2. 8-bit packet type (unsigned char) sent before packet struct
**			(see below)
**
*/

/*
**	Protocol control codes (8-bits each)
**
*/
#define NNAUDIO_CTL_OK			0	/* success/ok condition	*/
#define NNAUDIO_CTL_ERR			1	/* error condition	*/
#define NNAUDIO_CTL_ACK			2	/* acknowledgement	*/
#define NNAUDIO_CTL_NAK			3	/* not acknowledgement	*/

/*
**	Protocol packet type codes (8 bits each)
**
*/
#define NNAUDIO_TYPE_CAPS		100	/* audio capabilities	*/
#define NNAUDIO_TYPE_PROGRAM		101	/* program DSP		*/
#define NNAUDIO_TYPE_AUDIO		102	/* audio data		*/

/*
**	Audio encoding types
**
*/
#define NNAUDIO_ENCODING_ULAW		0x01	/* uLaw encoding	*/
#define NNAUDIO_ENCODING_ALAW		0x02	/* aLaw encoding	*/
#define NNAUDIO_ENCODING_LINEAR		0x04	/* signed linear PCM	*/
#define NNAUDIO_ENCODING_LINEAR8	0x08	/* 8bit unsigned linear	*/

/*
**	NNAUDIO_PKT_CAPS:
**		Describes remote audio capabilities
**
*/
typedef struct
{
	unsigned short samplerate_min;		/* min sample rate, Hz	*/
	unsigned short samplerate_max;		/* max sample rate, Hz	*/
	unsigned short channels;		/* number of channels	*/
	unsigned short bits_min;		/* min bits per sample	*/
	unsigned short bits_max;		/* max bits per sample	*/
	unsigned char  encodings;		/* 8-bit encodings mask	*/
}
NNAUDIO_PKT_CAPS;

/*
**	NNAUDIO_PKT_PROGRAM:
**		Sent to audio server to program the DSP
**
*/
typedef struct
{
	unsigned short samplerate;		/* sample rate, Hz	*/
	unsigned short channels;		/* number of channels	*/
	unsigned short bits;			/* bits per sample	*/
	unsigned char  encoding;		/* encoding type	*/
}
NNAUDIO_PKT_PROGRAM;

/*
**	NNAUDIO_PKT_AUDIO:
**		DSP Audio fragment data
**
*/
#define NNAUDIO_MAX_AUDIO_SIZE	32768		/* 32KB max frag	*/
typedef struct
{
	unsigned short size;			/* byte size of frag	*/
	unsigned char  data[0];			/* data (see size)	*/
}
NNAUDIO_PKT_AUDIO;


#endif	/* NNAUDIO_H_INCLUDED	*/

------nnaudio.h: cut here ------

