src/add-ons/media/media-add-ons/esound_sink/EsounD-protocol.txt

   1 EsounD Protocol (Draft)
   2 Author: ymnk<ymnk@jcraft.com>
   3 Data: 2000-10-02
   4 ===============
   5
   6 Introduction
   7 ------------
   8 This document describes the protocol in EsounD system.
   9 Unfortunately, any formal description about EsounD had not existed.
  10 So the author has tried to read the source code of EsounD and written this
  11 document. The author is also the author of JEsd, which is a re-implementation
  12 of EsounD in pure Java and this document is based on his knowledge,
  13 which had gotten in hacking JEsd.
  14
  15
  16 Connection Setup
  17 ----------------
  18 The esd will wait for the TCP connection requests from EsounD compatible
  19 applications. In the default, esd will listen to the TCP port 16001.
  20 The client must send an initial byte of data to be authorized them-self
  21 and to identify the byte order to be employed.
  22 For authorization, client must send 'esd-key', which is a 16 byte data.
  23 For endian-ness, client must send a 4 byte data.
  24 If esd does not detect any error, '1' will be sent back and
  25 '0' will be sent back in error.
  26
  27 Requests
  28 --------
  29   lock:
  30     esd-key:ESDKEY
  31   w result:BOOLEAN
  32
  33   At first, esd will check if the client has the right to lock the device
  34   by esd-key. If that client has the right to do so, esd will lock the device
  35   and send back true. If not, false will be sent back
  36
  37   unlock:
  38     esd-key:ESDKEY
  39   w result:BOOLEAN
  40
  41   At first, esd will check if the client has the right to unlock the device
  42   by esd-key. If that client has the right to do so, esd will unlock the
  43   device and send back true. If not, false will be sent back
  44
  45   ...
  46
  47
  48
  49 Syntactic Conventions
  50 --------------------
  51 All numbers are in decimal, unless prefixed with '0x', in which case
  52 they are in hexadecimal(base 16).
  53
  54 The general syntax used to describe data packets is:
  55   Name:
  56        encoded-form
  57        ...
  58        encoded-form
  59
  60 For components described in the protocol descriptions as:
  61   name: TYPE
  62   w name: TYPE
  63 the encode-form are:
  64        N  TYPE        name
  65 and
  66 w      N  TYPE        name
  67 N is the number of bytes in the data stream, and TYPE is the interpretation
  68 of those bytes. For example,
  69   result: BOOLEAN
  70 becomes:
  71        4 BOOLEAN     result
  72
  73 For components with a static numeric value the encode-form is:
  74        N value       name
  75 The value is always interpreted as a N-byte unsigned integer.
  76
  77
  78 Data Types
  79 ----------
  80   CARD8: A single byte unsigned integer.
  81   CARD32: 32-bit unsigned integer
  82   ARRAY8: A collection of CARD8.
  83   ARRAY8(n): This is a ARRAY8, which includes 'n' elements.
  84   ENDIAN: This is a ARRAY8(4), which includes 'ENDN' or 'NDNE'.
  85           If the first element is 'E', data from clients is in big-endian.
  86   BOOLEAN: This is a CARD32 and includes '0' or '1'. '1' means true.
  87   ESDKEY: This is a ARRAY8(16), which includes 'esd-key'.
  88   ESDNAME: This is a ARRAY8(128), which includes 'esd-name'.
  89   ESDSTREAM: This is a infinite ARRAY8.
  90   FORMAT: This is a CARD32. Each bits in this data has following semantics,
  91           (format&0x000f)==0x0000  8bit data
  92           (format&0x000f)==0x0001  16bit data
  93           (format&0x00f0)==0x0010  mono
  94           (format&0x00f0)==0x0020  stereo
  95           (format&0x0f00)==0x0000  stream
  96           (format&0x0f00)==0x0100  sample
  97           (format&0x0f00)==0x0200  ADPCM
  98           (format&0xf000)==0x1000  play
  99           (format&0xf000)==0x0000  monitor for streams, stop for samples
 100           (format&0xf000)==0x2000  record for streams, loop for samples
 101   MODE: This is a CARD32, which is '0', '1', '2' or '3'.
 102           0 ERROR
 103           1 STANDBY
 104           2 AUTOSTANDBY
 105           3 RUNNING
 106
 107
 108 Packet Format
 109 -------------
 110   init:
 111        4  0            opcode
 112       16  ESDKEY       esd-key
 113        4  ENDIAN       'ENDN' or 'NDNE'
 114   w    4  BOOLEAN      0 or 1
 115
 116
 117   lock:
 118        4  1            opcode
 119       16  ESDKEY       esd-key
 120        4  ENDIAN       unused
 121   w    4  BOOLEAN      0 or 1
 122
 123   unlock:
 124        4  2            opcode
 125       16  ESDKEY       esd-key
 126        4  ENDIAN       unused
 127   w    4  BOOLEAN      0 or 1
 128
 129   stream-play:
 130        4  3            opcode
 131        4  FORMAT       format
 132        4  CARD32       rate
 133      128  ESDNAME      name
 134        ?  ESDSTREAM    stream of PCM sound
 135
 136 //stream-mon:         This protocol is not used for the remote esd.
 137 //     4  4           opcode
 138 //     4  FORMA       format
 139 //     4  CARD3       rate
 140 //   128  ESDNAME     name
 141 //  w  ?  ESDSTREAM   stream of PCM sound
 142
 143   stream-mon:
 144        4  5            opcode
 145        4  FORMAT       format
 146        4  CARD32       rate
 147      128  ESDNAME      name
 148   w    ?  ESDSTREAM    stream of PCM sound
 149
 150   sample-cache:
 151        4  6            opcode
 152        4  FORMAT       format
 153        4  CARD32       rate
 154        4  n            size
 155      128  ESDNAME      name
 156   w    4  CARD32       sample-id
 157        n  ARRAY8(n)    stream of PCM sound
 158   w    4  CARD32       sample-id
 159
 160   sample-free:
 161        4  7            opcode
 162        4  CARD32       sample-id
 163   w    4  CARD32       sample-id
 164
 165   sample-play:
 166        4  8            opcode
 167        4  CARD32       sample-id
 168   w    4  CARD32       sample-id
 169
 170   sample-loop:
 171        4  9            opcode
 172        4  CARD32       sample-id
 173   w    4  CARD32       sample-id
 174
 175   sample-stop:
 176        4  10           opcode
 177        4  CARD32       sample-id
 178   w    4  CARD32       sample-id
 179
 180   sample-kill:
 181        4  11           opcode
 182        4  CARD32       sample-id
 183   w    4  CARD32       sample-id
 184
 185   standby:
 186        4  12           opcode
 187       16  ESDKEY       esd-key
 188        4  ENDIAN       unused
 189   w    4  BOOLEAN      0 or 1
 190
 191   resume:
 192        4  13           opcode
 193       16  ESDKEY       esd-key
 194        4  ENDIAN       unused
 195   w    4  BOOLEAN      0 or 1
 196
 197   sample-getid:
 198        4  14           opcode
 199      128  ESDNAME      name
 200   w    4  CARD32       sample-id
 201
 202   stream-filter:
 203        4  15           opcode
 204        4  FORMAT       format
 205        4  CARD32       rate
 206      128  ESDNAME      name
 207   w    4  BOOLEAN      0 or 1
 208
 209   server-info:
 210        4  16           opcode
 211   w    4  CARD32       version
 212   w    4  CARD32       rate
 213   w    4  FORMAT       format
 214
 215   server-all-info:
 216        4  17           opcode
 217   w    4  CARD32       version
 218   w    4  CARD32       rate
 219   w    4  FORMAT       format
 220   w    ?  STREAMINFO
 221   w    ?  SAMPLEINFO
 222
 223 STREAMINFO:
 224   except for last in series
 225   w    4  CARD32       id
 226   w   16  ESDNAME      name
 227   w    4  CARD32       rate
 228   w    4  CARD32       left-vol-scale
 229   w    4  CARD32       right-vol-scale
 230   w    4  FORMAT       format
 231   last in series
 232   w    4  CARD32       0
 233   w   32  ARRAY8(32)   unused
 234
 235
 236 SAMPLEINFO:
 237   except for last in series
 238   w    4  CARD32       id
 239   w   16  ESDNAME      name
 240   w    4  CARD32       rate
 241   w    4  CARD32       left-vol-scale
 242   w    4  CARD32       right-vol-scale
 243   w    4  FORMAT       format
 244   w    4  CARD32       sample-length
 245   last in series
 246   w    4  CARD32       0
 247   w   36  ARRAY8(36)   unused
 248
 249
 250 //subscribe:                        undefined
 251 //     4  18           opcode
 252
 253 //unsubjcribe:                      undefined
 254 //     4  19           opcode
 255
 256   stream-pan:
 257        4  20           opcode
 258        4  CARD32       stream-id
 259        4  CARD32       left-scale
 260        4  CARD32       right-scale
 261   w    4  BOOLEAN       0 or 1
 262
 263   sample-pan:
 264        4  21           opcode
 265        4  CARD32       sample-id
 266        4  CARD32       left-scale
 267        4  CARD32       right-scale
 268   w    4  BOOLEAN       0 or 1
 269
 270
 271   standby-mode:
 272        4  22           opcode
 273        4  0            version
 274   w    4  MODE         mode
 275   w    4  BOOLEAN      0 or 1
 276
 277   latency:
 278        4  23           opcode
 279   w    4  CARD32       latency