README

   1 ================================================================================
   2
   3                             On-Screen Display Daemon
   4
   5                        (c) 2010 Martin Mares <mj@ucw.cz>
   6
   7        You can use and distribute this program under the terms of GPLv2.
   8
   9 ================================================================================
  10
  11
  12 OSDD is a simple daemon whose purpose is to wait for messages sent by other
  13 programs and display them on the screen using libxosd. Unlike other such
  14 daemons, it handles message attributes (like colors), keeps its eye on
  15 message timing and uses X properties to pass messages, so it works over SSH
  16 connections with X forwarding (however, you need to use "ssh -Y" instead of
  17 "ssh -X" with newer versions of OpenSSH).
  18
  19 I have developed osdd on Linux, but it should work on any recent POSIX-compliant
  20 system equipped with libX11 and libxosd.
  21
  22 Please send all bug reports and suggestions to the author.
  23
  24 Usage
  25 ~~~~~
  26 When you run `osdd' without any parameters, it forks and waits in the background
  27 to serve the messages. It is convenient to invoke it from ~/.xsession, so that
  28 it is started with your X session. It should exit properly when the session
  29 terminates.
  30
  31 The simplest way of sending messages to the daemon is using the `osdc' client,
  32 e.g., `osdc "Hello world!"'. Use multiple parameters to create a multi-line
  33 message (however, the maximum number of lines is fixed and it can be changed
  34 only by the `--lines' switch on daemon startup).
  35
  36 You can also add attributes to the message (written as command-line options):
  37
  38   --color=c             Set foreground color of the message. Colors are specified
  39                         either as #RGB, or #RRGGBB, or color names from X11 rgb.txt,
  40                         or any other method documented in XParseColor(3).
  41
  42   --outline-color=c     Set color of character outlines.
  43
  44   --duration=ms         Show the message for a given number of miliseconds.
  45
  46   --min-duration=ms     When another message arrives while this one is displayed,
  47                         the duration of this message can be shortened, but not
  48                         below this parameter.
  49
  50   --percent=p           Draw a line with a percentage bar (p=0..100)
  51
  52   --slider=p            Draw a line with a slider (p=0..100)
  53
  54 The default values of most of these attributes can be given by command-line
  55 options of the daemon, use `osdd --help' to get the full list.
  56
  57 Any value can be replaced by "-", meaning "read from standard input".
  58
  59
  60 Example clients
  61 ~~~~~~~~~~~~~~~
  62
  63 osd-clock               Display current date and time (a shell script piping
  64                         its output to osdc).
  65
  66 osd-mpc-volume          Adjust volume of the MPD music player daemon and show
  67                         a slider with the new value.
  68
  69 osd-batt                A slightly more complex client written in C, showing
  70                         the current status of laptop batteries. It can be asked
  71                         to show status immediately or to run in background and
  72                         croak whenever the battery is low.
  73
  74 osd-alsa                Adjust volume of an ALSA mixer channel. Also written in C.