dtas.git  about / heads / tags
duct tape audio suite for *nix
blob a14686851ee531058a7c4974d5a2621b9c8941c7 3886 bytes (raw)
name: Documentation/dtas-player.pod 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
% dtas-player(1) dtas user manual

=head1 NAME

dtas-player - playback process for dtas

=head1 SYNOPSYS

dtas-player

=head1 DESCRIPTION

dtas-player is intended as a music player, but implemented as Unix
process and pipeline manager, so it may run arbitrary commands and route
data to just about any process.

dtas-player is currently only queue-based, enqueued tracks are played
only once.  It only runs in a foreground console, so usage with
L<screen(1)> or L<tmux(1)> is recommended.

By default, dtas-player uses the L<sox(1)> command to decode audio, and
pipes the data to a L<play(1)> process (also distributed with sox).  It may
be configured to output to multiple/arbitrary processes, and may invoke
arbitrary commands for outputting audio (or any other data).

dtas-player is controlled by a Unix socket, see L<dtas-player_protocol(7)>
for details.  Given the power of dtas-player to run arbitrary commands,
this socket is created with restricted permissions and is only
accessible by the user who invoked dtas-player.

dtas-player maintains state across restarts with a state file.

=head1 EXAMPLE

Starting dtas-player is easy, it takes no arguments:

    $ dtas-player

In a different terminal, enqueue your favorite track for playback:

    $ dtas-enq /path/to/your/favorite/music.flac

In the terminal running dtas-player, some diagnostic information
should be printed, as will any errors which occur.

To see information about the currently playing track in YAML:

    $ dtas-ctl current

As you should be able to see, a "default" sink is automatically
created and playing the audio.

=head1 TROUBLESHOOTING

=head2 Audio playback does not start

The most common problem with dtas-player is the L<play(1)> command
(distributed with SoX) not using the correct audio device/driver.
Ensuring the L<play(1)> command works with dtas-player is important.
Consult SoX documentation and mailing lists for getting L<play(1)> to work,
first.

Once you find the correct AUDIODEV/AUDIODRIVER environment variables,
you may set them via L<dtas-ctl(1)>:

To play audio on my favorite USB DAC directly to ALSA, I use:

    $ dtas-ctl sink ed default env.AUDIODEV=hw:DAC env.AUDIODRIVER=alsa

=head2 Seeking/playing audio from large video containers (e.g. VOB) fails

This is a problem with large VOBs.  We recommend breaking up the
VOB into smaller files or using L<avconv(1)> or L<ffmpeg(1)> to extract
the desired audio stream.

      avconv -analyzeduration 2G -probesize 2G \
        -i input.vob -vn -sn -c:a copy -map 0:$STREAM_NR output.ext

=head1 ADVANCED EXAMPLES

See L<dtas_player-sink_examples(7)> for more sink examples.

=head1 ENVIRONMENT

DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
This defaults to ~/.dtas/player.sock

DTAS_PLAYER_STATE - the state file of the dtas-player
This defaults to ~/.dtas/player_state.yml

dtas-player will automatically populate $SOXFMT and $ECAFMT when
invoking sink and source commands.

ReplayGain values are also exported to the source command if they
exist in the source file:

    * REPLAYGAIN_TRACK_GAIN
    * REPLAYGAIN_ALBUM_GAIN
    * REPLAYGAIN_ALBUM_PEAK
    * REPLAYGAIN_TRACK_PEAK

=head1 FILES

~/.dtas/player_state.yml is a human-readable YAML file used to preserve
state across restarts of dtas-player.

=head1 CONTACT

All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>

Mailing list archives available at L<http://80x24.org/dtas-all/>
and L<ftp://lists.gnu.org/dtas-all/>

No subscription is necessary to post to the mailing list.

=head1 COPYRIGHT

Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>

License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>

=head1 SEE ALSO

L<dtas-player_protocol(7)>, L<dtas-ctl(1)>, L<dtas-enq(1)>,
L<dtas-sourceedit(1)>, L<dtas-sinkedit(1)>, L<sox(1)>, L<play(1)>,
L<avconv(1)>, L<ffmpeg(1)>, L<screen(1)>, L<tmux(1)>

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

git clone git://80x24.org/dtas.git
git clone https://80x24.org/dtas.git