<commit_before>.Dd July 26, 2014
.Dt PLAYSLAVE++ 1
.Os 
.Sh NAME
.Nm playslave++
.Nd basic TCP/IP-driven audio player
.Sh SYNOPSIS
.Nm
.Op Ar device-id
.Op Ar address
.Op Ar port
.Sh DESCRIPTION
.Nm
is a very simple audio playback program, intended to be driven by other, more
complex software.  Think of it as
.Xr mpd 1 ,
but on a diet.

.Nm
has a very simple feature list: it can load one audio file (given its path), it
can play that file, it can pause playback of that file, it can seek and eject
that file, and it periodically sends back the current position in that file.
It is controlled via a simple, line-of-text-based protocol exposed as a TCP
server.

If supplied with zero arguments,
.Nm
enumerates the possible values for the
.Ar device-id
argument.  Otherwise, it is launched according to the provided arguments, the
meaning of which is as follows:
.Bl -tag -width "device-id"
.It Ar device-id
The ID of the device onto which
.Nm
will output audio.  This must be one of the values provided when
.Nm
is executed with zero arguments.  Additionally, it must refer to a device
capable of audio output.
.It Ar address
If provided, this specifies the TCP/IP address to which
.Nm
will bind when listening for client connections.  Typical values include
127.0.0.1 (connections from localhost only) and 0.0.0.0 (connections from
anywhere).  The default is 127.0.0.1.
.It Ar port
If provided, this specifies the TCP/IP port on which
.Nm
will listen for client connections.  The default is 1350.
.El
.Ss Protocol
.Nm
speaks a text-based protocol which is simple to understand but, for reasons of
brevity (and the fact that the protocol is not yet finalised and may quickly
outpace this man page in development), is not documented here.  Refer to
https://github.com/UniversityRadioYork/playslave-plusplus/wiki/Playslave-API
for the latest protocol documentation.
.Ss Controlling from a terminal
Since
.Nm
only speaks TCP/IP (by design), it can be difficult to speak with it from a
terminal on the local machine.  We recommend the use of a program such as
.Xr nc 1
to bridge this gap in functionality.
.Sh EXAMPLES
The command

.Dl % playslave++

will produce a listing similar to the following:
.Bd -literal -offset indent
0: Microsoft Sound Mapper - Input
1: Microphone (Plantronics GameCom
2: SPDIF Interface (Plantronics Ga
3: Line (Plantronics GameCom 780)
4: Microsoft Sound Mapper - Output
5: Speakers (Plantronics GameCom 7
6: Digital Audio (S/PDIF) (2- High
7: Digital Audio (S/PDIF) (2- High
8: Digital Audio (S/PDIF) (2- High Definition Audio Device)
9: Speakers (Plantronics GameCom 780)
10: Digital Audio (S/PDIF) (2- High Definition Audio Device)
11: Microphone (Plantronics GameCom 780)
12: SPDIF Interface (Plantronics GameCom 780)
13: Line (Plantronics GameCom 780)
.Ed

Suppose we want
.Nm
to output on the Microsoft Sound Mapper. (Naturally, if you're reading this man
page, chances are this isn't an option; please excuse the use of Windows-based
examples!)  The command

.Dl % playslave++ 4

will start
.Nm
on its default address (localhost) and port, outputting on device ID 4.

If we should need more control over the address and port, we may supply them as
additional arguments, for example:

.Dl % playslave++ 4 127.0.0.1 1350

To now connect to
.Nm
from the local terminal, one can use a command such as:

.Dl % nc 127.0.0.1 1350

This example, hopefully, covers all command-line usage of
.Nm .
.Sh AUTHORS
.An "<NAME>" Aq <EMAIL>
.An "<NAME>" Aq <EMAIL>
.Sh BUGS
Yes.  See https://github.com/UniversityRadioYork/playslave-plusplus/issues for
the
.Nm
issue tracker.
<commit_msg>Use ALSA for man page example.<commit_after>.Dd July 26, 2014
.Dt PLAYSLAVE++ 1
.Os
.Sh NAME
.Nm playslave++
.Nd basic TCP/IP-driven audio player
.Sh SYNOPSIS
.Nm
.Op Ar device-id
.Op Ar address
.Op Ar port
.Sh DESCRIPTION
.Nm
is a very simple audio playback program, intended to be driven by other, more
complex software.  Think of it as
.Xr mpd 1 ,
but on a diet.

.Nm
has a very simple feature list: it can load one audio file (given its path), it
can play that file, it can pause playback of that file, it can seek and eject
that file, and it periodically sends back the current position in that file.
It is controlled via a simple, line-of-text-based protocol exposed as a TCP
server.

If supplied with zero arguments,
.Nm
enumerates the possible values for the
.Ar device-id
argument.  Otherwise, it is launched according to the provided arguments, the
meaning of which is as follows:
.Bl -tag -width "device-id"
.It Ar device-id
The ID of the device onto which
.Nm
will output audio.  This must be one of the values provided when
.Nm
is executed with zero arguments.  Additionally, it must refer to a device
capable of audio output.
.It Ar address
If provided, this specifies the TCP/IP address to which
.Nm
will bind when listening for client connections.  Typical values include
127.0.0.1 (connections from localhost only) and 0.0.0.0 (connections from
anywhere).  The default is 127.0.0.1.
.It Ar port
If provided, this specifies the TCP/IP port on which
.Nm
will listen for client connections.  The default is 1350.
.El
.Ss Protocol
.Nm
speaks a text-based protocol which is simple to understand but, for reasons of
brevity (and the fact that the protocol is not yet finalised and may quickly
outpace this man page in development), is not documented here.  Refer to
https://github.com/UniversityRadioYork/playslave-plusplus/wiki/Playslave-API
for the latest protocol documentation.
.Ss Controlling from a terminal
Since
.Nm
only speaks TCP/IP (by design), it can be difficult to speak with it from a
terminal on the local machine.  We recommend the use of a program such as
.Xr nc 1
to bridge this gap in functionality.
.Sh EXAMPLES
The command

.Dl % playslave++

will produce a listing similar to the following:
.Bd -literal -offset indent
0: HDA ATI SB: ALC892 Analog (hw:0,0)
1: HDA ATI SB: ALC892 Digital (hw:0,1)
2: HDA ATI SB: ALC892 Alt Analog (hw:0,2)
3: HDA NVidia: ID 42 Digital (hw:1,3)
4: Plantronics GameCom 780: USB Audio (hw:2,0)
5: sysdefault
6: front
7: surround40
8: default
9: dmix
.Ed

Suppose we want
.Nm
to output on the GameCom.  The command

.Dl % playslave++ 4

will start
.Nm
on its default address (localhost) and port, outputting on device ID 4.

If we should need more control over the address and port, we may supply them as
additional arguments, for example:

.Dl % playslave++ 4 127.0.0.1 1350

To now connect to
.Nm
from the local terminal, one can use a command such as:

.Dl % nc 127.0.0.1 1350

This example, hopefully, covers all command-line usage of
.Nm .
.Sh AUTHORS
.An "<NAME>" Aq <EMAIL>
.An "<NAME>" Aq <EMAIL>
.Sh BUGS
Yes.  See https://github.com/UniversityRadioYork/playslave-plusplus/issues for
the
.Nm
issue tracker.

{'fraction_non_alphanumeric': 0.07076514816452897, 'fraction_numerical': 0.026242075777679494, 'mean_word_length': 3.849177984274482, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '451628', 'n_tokens_mistral': 2295, 'n_tokens_neox': 2130, 'n_words': 1089}