psycamp deserves proper perldoc!

1 files changed, 252 insertions, 171 deletions

diff --git a/bin/psycamp b/bin/psycamp
index 821c6b8..2502819 100755
--- a/bin/psycamp
+++ b/bin/psycamp
@@ -3,15 +3,7 @@
 my $TITLE = "PSYC media console 4.0";
 my $AUTHOR = "by the symbolic lynX\@psycamp.pages.de";
 
-# been around as 'psycmp3' for almost twenty years, but since 2017 it
-# can also play other formats.. so i shalt rename it to 'psycamp'
-#
-# command line front-end to audio engines with PSYC remote control
-#
-# this media player is over a decade old, but it still is my tool of
-# choice. i gave it functions i didn't find in any other.. like,
-# how useful is a media player if you can't easily reorganize or at
-# least delete files you don't want to consume ever again?
+# see end of file for end-user-oriented documentation
 #
 # uses 'mplayer' - the most popular media player on linux with the
 # worst scripting API ever seen in a lifetime. it is documented
@@ -23,16 +15,14 @@ my $AUTHOR = "by the symbolic lynX\@psycamp.pages.de";
 # been using since 1997 or so has a sha256sum of
 # ddb096ad42d9b6b543db8a3a6d9b4a9d52943e75e96697dbbadbc779140c498e.
 # although the general public never saw any source codes to it, it is
-# viable to assume that it didn't ship any backdoors. grab a copy from 
+# viable to assume that it's not a trojan. grab a copy from 
 # http://mp3.pages.de/files/rxaudio
 #
-# furthermore psycamp requires the Net/PSYC.pm module since it uses its 
-# event multiplexing abilities, not just to receive PSYC messages, but
+# psycamp requires the Net/PSYC.pm module since it uses its event 
+# multiplexing abilities, not just to receive PSYC messages, but
 # also to handle stdin and engine input in parallel.
 #
-# you can use the 'psyccmd' script to remote control this script, which 
-# therefore can act as a music jukebox or media player daemon. also,
-# psycamp can obviously generate 'playing now' notifications.
+# things still in "makenoise":  marks, volume levels.
 
 # since perl has no native preprocessor, this code is
 # managed by the 'jaggler' preprocessor.
@@ -43,85 +33,19 @@ my $AUTHOR = "by the symbolic lynX\@psycamp.pages.de";
 #  'X' := "rxaudio" - use the old mp3 engine instead of mplayer
 #
 # psycamp in 'distribution' default mode
-#       jaggler -x -c# -j% psycamp
+#       jaggler -x -c# -j% -DO psycamp
 # psycamp supporting 'T' and 'O' extras:
 #       jaggler -x -c# -j% -DOT psycamp
 
-# things still in "makenoise":  cdrom-file-caching, des-decoding,
-#                               marks, volumes, support for non-mp3s.
-#
 # HINTS & HACKS:
 # in order to play only high quality files from a folder, you can use
-# "lm -Lb 193 >/tmp/playlist-$USER.m3u; psycamp"
+#       "lm -Lb 193 >/tmp/playlist-$USER.m3u; psycamp"
 # lm is available from http://perl.pages.de. such functionality could
 # obviously be integrated into here, allowing us also to remove file
-# type guessing - but in exchange we slow down the playlist creation
-# process if every file were thrown at ffmpeg to discover its media
+# type guessing - but that would slow down the playlist creation
+# process, if every file were thrown at ffmpeg to discover its media
 # properties.
 
-use Term::ANSIColor qw( :constants );
-use Term::ReadKey qw(GetTerminalSize);
-($TWIDTH, $THEIGHT) = GetTerminalSize();
-
-sub help { print BOLD, BLACK, &head, RESET, <<X, &sep('='); }
-
-basics: (q)uit (h)elp
-
-motion: (p)lay (s)top pa(u)se
-      [ j(ump) ] <mm:ss>                jump to an absolute point in the song
-      [ (g)oto ] <pos> [<range>]         can do smart guessing of range value
- (for example you can simply type '0' thru '9' to jump to a point in the song)
-
-files:  (o)pen <file>                          immediately load this new song
-        <file>              a filename by itself will first fade current song
-        (l)ist [<dir>]                                       simply calls 'ls'
-        (n)ext                                        next file from playlist
-        '?'                      show a list of the next 9 songs in the queue
-        (w)rite or (e)dit playlist
-        e(x)it                                  exit without updating playlist
-
-volume: (v)olume [0..100]                           default is maximum volume
-        v+  v-                              increase or decrease volume a bit
-        (f)ade [<volume> [<psecs>]]          psecs: time between volume steps
-        (r)ise [<volume> [<psecs>]]                    (example: fade 33 0.1)
-
-extra commands for scripting:
-        sleep <time>    wait for <time> before executing next command
-
-type (H)elp for organizing commands
-X
-
-# when organizing mode has been activated in psycamp, you can reorganize
-# your media files as follows:
-sub help2 { print BOLD, BLACK, &head, RESET, <<X, &sep('='); }
-
-whenever media is in a directory like INCOMING, NEW or TODO - it can be
-moved into a different subdirectory on the same hierarchy level by using
-the following uppercase commands:
-
-        J = send to DEEJAY folder
-        U = send to USE
-        K = send to KEEP
-        X = send to EXPORT
-        S = send to SECONDARY
-        R = send to REPERTOIRE
-
-if you prefer to execute the command *after* having finished playing it,
-you can schedule the move for later by doubling the command letter. so
-you type 'KK' if you want to keep the file after having listened to it.
-the commands for deleting items are similar:
-
-        D = delete the file now
-        DD = delete the file after having played it
-        T = delete the file and mark as trash
-        TT = mark as trash and delete later
-
-Consider also the -d and -D options which delete files automatically
-after consumption depending on the name of the directory.
-
-type (h)elp for regular commands
-X
-
 # default PSYC address for this service, UDP port 1144 on this host.
 # can be overridden with -b
 #
@@ -131,22 +55,24 @@ $UNI = 'psyc://127.0.0.1:1144d/';
 # remote control commands back to you, even if you bind localhost here.
 # you may like to have such chat-based remote control, or you may not..
 
-# volume values, since volume doesn't seem to be linear as it should
+# volume values, since volume doesn't seem to be linear as it should be.
 # at least not my soundcard, check for yourself..
 #
 @VV = ( 0,2,5,8,11,14,17,20,24,28,33,38,43,49,56,64,72,81,90,100 );
 
+# would prefer not to enumerate media formats understood by mplayer,
+# but it is tricky to sort out non-media files when recursively
+# spidering input directories.
+#
 # when running rxaudio, psycamp can only handle .mp3 and .sdj
 #   "part" and "dl" are the temporary filenames of some download tools
 $FILETYPES =
 #%      "(mp3|sdj|part|dl)";                                         #? X
         "(mp\\d|sdj|part|dl|flac|wav|aif|aiff|ogg|m4a|aac|opus|au)"; #? !X
-# "(sea|mod|gz|lha|Z|lzh|zip|s3m)"; # |med|mmd0)";
-# should also be able to handle .pls
 #
-# would prefer not to enumerate media formats understood by mplayer,
-# but it is tricky to sort out non-media files when recursively
-# spidering input directories.
+# 'makenoise' had support for these formats:
+# "(sea|mod|gz|lha|Z|lzh|zip|s3m)"; # |med|mmd0)";
+# should also be able to handle .pls..?
 
 # starting pcm volume. system volume is kept at maximum anyway.
 #%$VOL = 0;     #? X
@@ -189,15 +115,15 @@ sub PATHMATCH () { 12 }
 sub HATEINDEX () { "$ENV{HOME}/.media/TRASH-$ENV{HOST}.ix" }
 
 # default output for video is the main screen, so if you have
-# a second monitor, it makes sense to have the console there
+# a second monitor, it makes sense to run psycamp over there
 my $screen = 0;
 
-$tmpdir='/temp';
-$tmpdir='/tmp' unless -d $tmpdir and -w _;
-$tmpdir='.' unless -d $tmpdir and -w _;
-# $tmplock="$tmpdir/.psycamp-copylock";
-$playlist="$tmpdir/playlist-$ENV{USER}.m3u";
 
+### BEGINNING OF REGULAR CODE
+
+        require 5.000;
+        use POSIX ":sys_wait_h";
+        use Pod::Usage qw( pod2usage );
         use Getopt::Std;
         use Cwd qw(chdir);  # maintains PWD in ENV
         use File::Path qw(mkpath);
@@ -210,12 +136,21 @@ $playlist="$tmpdir/playlist-$ENV{USER}.m3u";
         use Net::PSYC qw( :event );
         # would need to extend this to actually use it:
         #use Audio::Play::MPlayer;
+        use Term::ANSIColor qw( :constants );
+        use Term::ReadKey qw(GetTerminalSize);
+        ($TWIDTH, $THEIGHT) = GetTerminalSize();
 
         *name   = *File::Find::name;    # ugly style works
         $scan = 0;
         my %I;
         my $CDUR = 0;
 
+        $tmpdir='/temp';
+        $tmpdir='/tmp' unless -d $tmpdir and -w _;
+        $tmpdir='.' unless -d $tmpdir and -w _;
+        # $tmplock="$tmpdir/.psycamp-copylock";
+        $playlist="$tmpdir/playlist-$ENV{USER}.m3u";
+
 MAIN: {
         if ($#ARGV >= 0) {
                 getopt('bMnsS');
@@ -230,34 +165,13 @@ MAIN: {
 
         print "Using playlist: $playlist\n" if $opt_v;
         if ($opt_h) {
-                print BOLD, BLACK, &head, RESET, <<X, &sorthelp;
-
-usage: $0 [<flags>] [-b <uniform>] [-n <nick>] [-s <mode>]
-          [-M <UNI>] [-S <screen>] [<files|dirs>]
-
-        [-b]ind PSYC uniform and accept commands from both PSYC and stdin
-        [-M] sends currently playing title to a monitoring entity via PSYC
-        [-n]ickname to use for monitoring, otherwise '$nick' will be used
-        [-S]creen number to display videos on (default: 0)
-        [-s] provides for several sort options, see below
-flags:
-        [-H] shows an explanation what this tool is good for, try it!
-        [-r]andomize using a smart shuffle algorithm, much better than "-s r"
-        [-m]ono output
-        [-v]erbose: shows some output from rxaudio
-        [-q]uiet: shows close to no output
-        [-c]alculate cumulative duration of selections
-        [-L]oad the tracks in the playlist only if they really exist
-        [-x] will terminate perl and exec xaudio, use only when short on memory
-        [-I]nitialize rxaudio anew for each song, special hack
-        [-d]elete files after playing if the path contains the word '$VOLATILE'.
-        [-D]elete files after playing unless the path contains the word '$KEEP'.
-
-    without arguments psycamp resumes from last run´s playlist.
-X
+                print BOLD, BLACK, &head, RESET, "\n";
+# Old options removed from SYNOPSYS:
 #       [-S]kip files if the path contains the word '$KEEP', dont play them.
 #       [-l]ist filenames, sizes and bitrates (for archive documentation)
-#         ... broken and prolly useless
+#       [-m]ono output
+#       [-I]nitialize rxaudio anew for each song, special hack
+                pod2usage;
                 exit;
         }
         # initialize randomizer
@@ -289,6 +203,7 @@ X
 #%          !$has_rxaudio       #? X
             !$has_mplayer       #? !X
         ) {
+                # this block of text not moved into pod because of $UNI
                 print BOLD, BLACK, &head, RESET, <<X;
 
 This media player brings you a threefold functionality which you may combine
@@ -374,7 +289,7 @@ Y
 enter (h) for help
 
 X
-        &gin('channels mono') if $opt_m;
+#%      &gin('channels mono') if $opt_m;    #? X
         $CS = -1;       # global var for current song
 
         &next(0);
@@ -409,21 +324,21 @@ sub head {
 }
 
  #{ X
-sub timeout {
-    if (!$paused) {
-        # HACK for rxaudio which sometimes gets enchanted
-        #y $trick = rand(2)>1 ? 'pause' : 'seek 1 1';
-        #y $trick = ('pause', 'seek 1 1', 'play')[rand(3)];
-        #y $trick = 'seek 1 1';
-#                   print " (kicking rxaudio with '$trick')\n" if DEBUG & 32;
-#                   &gin( $trick );
-        print RED, "\n\t\t(kick) ", RESET if DEBUG & 32;
+#%sub timeout {
+#%    if (!$paused) {
+#%      # HACK for rxaudio which sometimes gets enchanted
+#%      #y $trick = rand(2)>1 ? 'pause' : 'seek 1 1';
+#%      #y $trick = ('pause', 'seek 1 1', 'play')[rand(3)];
+#%      #y $trick = 'seek 1 1';
+#%#                 print " (kicking rxaudio with '$trick')\n" if DEBUG & 32;
+#%#                 &gin( $trick );
+#%      print RED, "\n\t\t(kick) ", RESET if DEBUG & 32;
 #%      &gin('seek 1 1'); #? X
-        &gin('seek 0 1'); #? !X
-        &gin('pause'); #? !X
-    }
-    return 3;
-}
+#%      &gin('seek 0 1'); #? !X
+#%      &gin('pause'); #? !X
+#%    }
+#%    return 3;
+#%}
  #} X
 
 sub ginread {
@@ -447,13 +362,13 @@ sub ginread {
             /^EOF code: 1\b/                        #? !X
         ) {
                 # &progress('');
-                if ($deleteLater eq $CurrentFile) {
+                if ($moveLater) {
+                    &moveFile($moveLater);
+                    $moveLater = undef;
+                } elsif ($deleteLater eq $CurrentFile) {
                     print RED, unlink ($deleteLater) ?
                             "\r***" : "\r - ", BOLD, GREEN, "[\n", RESET;
                     $deleteLater = undef;
-                } elsif ($moveLater) {
-                    &moveFile($moveLater);
-                    $moveLater = undef;
                 } elsif ($opt_d && ($Volatile ||
                     $CurrentFile =~ /\b$VOLATILE\b/oi)) {
                         print RED, unlink ($CurrentFile) ?
@@ -485,6 +400,11 @@ sub ginread {
 
 sub stdread {
     $_ = scalar <STDIN>;
+    # should be in timeout instead
+    if (waitpid(-1, WNOHANG)) {
+            print BOLD, RED, "\r>>> Media engine has terminated.", RESET, "\n";
+            exit;
+    }
     &parse( $_ );
 }
 
@@ -617,7 +537,7 @@ X
                         $f = '..'.substr($f,length($p)-$TWIDTH+16) if
                                 length($f) > $TWIDTH-14;
                         $any++;
-                        printf "%3d.%8d %s\n", $i, $s, $f;
+                        printf "%2d.%9d %s\n", $i, $s, $f;
                 }
                 print $any ? "\n" : "<no more songs in playlist>\n\n";
                 print &sep('-');
@@ -654,6 +574,7 @@ X
                 $_ = $1? 'DD': 'D';
             }
             if ( /^(_|DD)\s*$/ ) {
+                $moveLater = undef;
                 $deleteLater = $CurrentFile;
                 print BOLD, BLUE, ">> scheduled for removal\n", RESET;
                 next;
@@ -673,6 +594,7 @@ X
                         print BOLD, RED, ">> command $1$r not defined\n", RESET;
                         next;
                 }
+                $deleteLater = undef;
                 my $t = $1 eq 'J' ? 'DEEJAY' :
                         $1 eq 'U' ? 'USE' :
                         $1 eq 'K' ? 'KEEP' :
@@ -903,31 +825,16 @@ sub which {
 sub sortsongs {
         my $style = shift;
         return (1 .. $NS) unless $style;
-#       lc $style; -- eh? this breaks half of the algorithms
         my @order;
         print STDERR "sorting by_$style 1 .. $NS\n" if DEBUG & 8;
         eval "\@order = sort by_$style 1 .. $NS";
-        croak <<X, &sorthelp if $@;
-invalid sort option '$style'
-X
-        return @order;
-}
-sub sorthelp { return <<X; }
+        croak BOLD, RED, <<X, RESET if $@;
 
-available sort algorithms:
-        n(ame)          # sorts by file path (directory first)
-        N(ame)          # sorts by file ending (reverse of -n)
-        s(ize)          # hear silly small sound snippets first
-        S(ize)          # hear big epic pieces first
-        m(odification)  # hear newest tracks first
-        M(odification)  # hear oldest tracks first
-        a(ccessTime)    # hear tracks you haven't heard in a long time first
-        A(ccessTime)    # hear tracks you recently accessed first
-        cr              # gives the order given on commandline a slight shuffle
+Invalid sort option '$style'. Look up '$0 -h' again.
 
-you can append 'r' to each algorithm (as in 'nr' or 'Ar') to apply a slight 
-random shuffle of the items while roughly following the sorting principle.
 X
+        return @order;
+}
         # r(andom)      # bad randomizer algorithm (use -r instead)
 # this actually produces VERY pseudo random results, says randal
 # see http://www.perlmonks.org/?node_id=199901
@@ -1215,16 +1122,26 @@ sub ginparse {
         }
         if ( /^Starting playback/ ) {
                 if ( (!$I{duration} || !$I{bitrate}) and $has_ffmpeg and
+                  # while mplayer is starting to play the track
+                  # we fetch further information on it...
                   (my $pid = open3(my $FFW, my $FF, my $FFE,
                   $has_ffmpeg, '-i', $CurrentFile))) {
                     while(<$FF>) {
+                        # quite ridiculous that we have to also run
+                        # an ffmpeg to obtain track duration which
+                        # mplayer knows but does not show.
                         if (/\bDuration: (\d\d):(\d\d):(\d\d)\.\d\d.+ bitrate: (\d\d+) kb/ and $1 ne '00:00:00') {
                             my $hh = $1;
                             my $mm = $2;
                             my $ss = $3;
                             my $br = $4;
+                            # unfortunately the bitrate we got from
+                            # mplayer frequently just uses some frame
+                            # from the track, not producing a median
+                            # value for VBR tracks. amazing how people
+                            # still don't dig VBR after 20 years.
                             print RED, "\rInconsistent bitrate info: ", RESET,
-                              "$I{bitrate} vs $br\n" if !$opt_q and $br
+                              "$I{bitrate} vs $br\n" if $opt_v and $br
                               and $I{bitrate} and abs($br-$I{bitrate}) > 1;
                             $I{bitrate} = $br if $br;
                             $I{duration} = $hh eq '00' ? "$mm:$ss" : "$hh:$mm:$ss";
@@ -1233,7 +1150,6 @@ sub ginparse {
                             break;
                         }
                     }
-                    # no time for waitpid
                     close $FF;
                     close $FFW;
                     close $FFE;
@@ -1258,7 +1174,7 @@ sub ginparse {
 }
 
 sub ginstart {
-        return if $pid;
+        return if $GINPID;
         if ($opt_I) {
                 system("soundoff");
                 system("soundon");
@@ -1267,21 +1183,21 @@ sub ginstart {
         $R = new FileHandle; $R->autoflush;
         $W = new FileHandle; $W->autoflush;
  #{ X
-#%      $pid = open3( \*W, \*R, \*R, "$wrapper $has_rxaudio");
-#%      $pid || die "$wrapper $has_rxaudio: $!";
+#%      $GINPID = open3( \*W, \*R, \*R, "$wrapper $has_rxaudio");
+#%      $GINPID || die "$wrapper $has_rxaudio: $!";
 #%      &ginxpect('ready');
  #: X
         # -v is needed to receive the EOF!
         # '-osdlevel', '3' can be useful
         # to allow for fading we want to have the PCM channel,
         # this works for ALSA - does it fail otherwise?
-        $pid = open3( \*W, \*R, \*R, $has_mplayer, '-slave', '-idle', '-v', '-fs', '-zoom', '-screen', $opt_S || $screen, '-mixer-channel', 'PCM' );
+        $GINPID = open3( \*W, \*R, \*R, $has_mplayer, '-slave', '-idle', '-v', '-fs', '-zoom', '-screen', $opt_S || $screen, '-mixer-channel', 'PCM' );
         R->blocking(0);
-        $pid || die "$has_mplayer: $!";
+        $GINPID || die "$has_mplayer: $!";
         &ginxpect('^MPlayer');
  #} X
         print STDERR <<X if DEBUG & 64;
-audio engine running as $pid
+audio engine running as $GINPID
 X
         add( \*R, 'r', \&ginread );
         $output_open = 1;
@@ -1294,7 +1210,8 @@ sub ginstop {
         gin('quit');
  #} X
         close R;
-        undef $pid;
+        waitpid( $GINPID, 0 );
+        undef $GINPID;
         $output_open = 0;
 }
 sub ginclose {
@@ -1367,3 +1284,167 @@ sub edit {
         &printinfo;
 }
 
+sub help { print BOLD, BLACK, &head, RESET, <<X, &sep('='); }
+
+basics: (q)uit (h)elp
+
+motion: (p)lay (s)top pa(u)se
+      [ (j)ump ] <mm:ss>                jump to an absolute point in the song
+      [ (g)oto ] <pos> [<range>]         can do smart guessing of range value
+ (for example you can simply type '0' thru '9' to jump to a point in the song)
+
+files:  (o)pen <file>                          immediately load this new song
+        <file>              a filename by itself will first fade current song
+        (l)ist [<dir>]                                       simply calls 'ls'
+        (n)ext                                        next file from playlist
+        '?'                      show a list of the next 9 songs in the queue
+        (w)rite or (e)dit playlist
+        e(x)it                                  exit without updating playlist
+
+volume: (v)olume [0..100]                           default is maximum volume
+        v+  v-                              increase or decrease volume a bit
+        (f)ade [<volume> [<psecs>]]          psecs: time between volume steps
+        (r)ise [<volume> [<psecs>]]                    (example: fade 33 0.1)
+
+extra commands for scripting:
+        sleep <time>    wait for <time> before executing next command
+
+type (H)elp for organizing commands
+X
+
+ #{ O
+# when organizing mode has been activated in psycamp, you can reorganize
+# your media files as follows:
+sub help2 { print BOLD, BLACK, &head, RESET, <<X, &sep('='); }
+
+Whenever media is in a directory like INCOMING, NEW or TODO, it can be
+moved into a different subdirectory on the same hierarchy level by using
+the following uppercase commands:
+
+        J = send to DEEJAY folder
+        U = send to USE
+        K = send to KEEP
+        X = send to EXPORT
+        S = send to SECONDARY
+        R = send to REPERTOIRE
+
+If you prefer to execute the command *after* having finished playing it,
+you can schedule the move for later by doubling the command letter. So
+you type 'KK' if you want to keep the file after having listened to it.
+You can change your mind while the track is playing - the last command
+you schedule is the one that counts.
+The commands for deleting items are similar:
+
+        D = delete the file now
+        DD = delete the file after having played it
+        T = delete the file and mark as trash
+        TT = mark as trash and delete later
+
+Consider also the -d and -D options which delete files automatically
+after consumption depending on the name of the directory.
+
+type (h)elp for regular commands
+X
+ #: O
+#%sub help2 { print RED, "\r", <<X, RESET, "\n"; }
+#%Sorry, organizing functions have been disabled.
+#%X
+ #} O
+
+__END__
+
+=pod
+
+=head1 NAME
+
+ psycamp - command line media player with PSYC remote control
+
+=head1 SYNOPSIS
+
+ psycamp [<flags>] [-b <uniform>] [-n <nick>] [-s <sort-algorithm>]
+         [-M <UNI>] [-S <screen>] [<media-files|directories>]
+
+        [-b]ind PSYC uniform and accept commands from both PSYC and stdin
+        [-M] sends currently playing title to a monitoring entity via PSYC
+        [-n]ickname to use for monitoring, otherwise a default will be used
+        [-s]ort playlist according to one of the algorithms explained below
+        [-S]creen number to display videos on (default: 0)
+
+ Flags:
+        [-H] shows an explanation what this tool is good for, try it!
+        [-r]andomize using a smart shuffle algorithm, much better than "-s r"
+        [-v]erbose: shows some extra output
+        [-q]uiet: shows close to no output
+        [-c]alculate cumulative duration of selections
+        [-L]oad the tracks in the playlist only if they really exist
+        [-x] will terminate perl and exec mplayer, use when short on memory
+        [-d]elete files after playing if the path contains the word '$VOLATILE'.
+        [-D]elete files after playing unless the path contains the word '$KEEP'.
+
+ Without arguments, psycamp resumes from last run's playlist.
+
+=head2 Sort algorithms:
+
+        n(ame)          # sorts by file path (directory first)
+        N(ame)          # sorts by file ending (reverse of -n)
+        s(ize)          # hear silly small sound snippets first
+        S(ize)          # hear big epic pieces first
+        m(odification)  # hear newest tracks first
+        M(odification)  # hear oldest tracks first
+        a(ccessTime)    # hear tracks you haven't heard in a long time first
+        A(ccessTime)    # hear tracks you recently accessed first
+        cr              # gives the order given on commandline a slight shuffle
+
+ You can append 'r' to each algorithm (as in 'nr' or 'Ar') to apply a slight 
+ random shuffle of the items while roughly following the sorting principle.
+
+=head1 DESCRIPTION
+
+This has been around as 'psycmp3', but since 2017 it can also
+play other formats.. so I shalt rename it to 'psycamp', the
+psyc amplifier, or the psyca media player...  :)
+
+This media player is over a decade old, but it still is my tool of
+choice. I gave it functions i didn't find in any other..  How
+useful is a media player that can't easily reorganize or at least 
+delete files you don't want to consume ever again?
+
+For further help on how to actually use the beast, type 'h' and
+ENTER once it is playing some media.
+
+=head2 PSYC Remote Control
+
+You can use the 'psyccmd' script to remote control psycamp which 
+therefore can act as a music jukebox or media player daemon. You
+could be generating those PSYC messages from whichever other
+tool you find appropriate. The format is easy. You may need to
+use '-b' to bind to an accessible network interface.
+
+=head2 PSYC Notification
+
+psycamp can obviously generate 'playing now' notifications. Just
+provide '-M' and '-b' accordingly.
+
+=head1 CAVEATS
+
+psycamp uses a line mode interface. Each command needs to be
+submitted to the program by hitting the ENTER key.
+It's unusual, but not a problem.
+
+psycamp ignores so-called ID3. it expects tracks to have meaningful
+file and directory names instead, since that is where you need the 
+information when shuffling files around.
+
+When watching video with psycamp, keystrokes in the video frame
+will go directly to mplayer, bypassing psycamp. This is fine for
+several interactions but psycamp gets stuck if you quit mplayer.
+
+=head1 AUTHORS
+
+carlo von lynX.
+
+=head1 COPYRIGHT
+
+This program is free software, published under the Affero GNU Public
+License. A disclaimer isn't necessary in my country, nor do I need
+to mention the current year to assert a copyright.