EsounD Protocol (Draft) Author: ymnk Data: 2000-10-02 =============== Introduction ------------ This document describes the protocol in EsounD system. Unfortunately, any formal description about EsounD had not existed. So the author has tried to read the source code of EsounD and written this document. The author is also the author of JEsd, which is a re-implementation of EsounD in pure Java and this document is based on his knowledge, which had gotten in hacking JEsd. Connection Setup ---------------- The esd will wait for the TCP connection requests from EsounD compatible applications. In the default, esd will listen to the TCP port 16001. The client must send an initial byte of data to be authorized them-self and to identify the byte order to be employed. For authorization, client must send 'esd-key', which is a 16 byte data. For endian-ness, client must send a 4 byte data. If esd does not detect any error, '1' will be sent back and '0' will be sent back in error. Requests -------- lock: esd-key:ESDKEY w result:BOOLEAN At first, esd will check if the client has the right to lock the device by esd-key. If that client has the right to do so, esd will lock the device and send back true. If not, false will be sent back unlock: esd-key:ESDKEY w result:BOOLEAN At first, esd will check if the client has the right to unlock the device by esd-key. If that client has the right to do so, esd will unlock the device and send back true. If not, false will be sent back ... Syntactic Conventions -------------------- All numbers are in decimal, unless prefixed with '0x', in which case they are in hexadecimal(base 16). The general syntax used to describe data packets is: Name: encoded-form ... encoded-form For components described in the protocol descriptions as: name: TYPE w name: TYPE the encode-form are: N TYPE name and w N TYPE name N is the number of bytes in the data stream, and TYPE is the interpretation of those bytes. For example, result: BOOLEAN becomes: 4 BOOLEAN result For components with a static numeric value the encode-form is: N value name The value is always interpreted as a N-byte unsigned integer. Data Types ---------- CARD8: A single byte unsigned integer. CARD32: 32-bit unsigned integer ARRAY8: A collection of CARD8. ARRAY8(n): This is a ARRAY8, which includes 'n' elements. ENDIAN: This is a ARRAY8(4), which includes 'ENDN' or 'NDNE'. If the first element is 'E', data from clients is in big-endian. BOOLEAN: This is a CARD32 and includes '0' or '1'. '1' means true. ESDKEY: This is a ARRAY8(16), which includes 'esd-key'. ESDNAME: This is a ARRAY8(128), which includes 'esd-name'. ESDSTREAM: This is a infinite ARRAY8. FORMAT: This is a CARD32. Each bits in this data has following semantics, (format&0x000f)==0x0000 8bit data (format&0x000f)==0x0001 16bit data (format&0x00f0)==0x0010 mono (format&0x00f0)==0x0020 stereo (format&0x0f00)==0x0000 stream (format&0x0f00)==0x0100 sample (format&0x0f00)==0x0200 ADPCM (format&0xf000)==0x1000 play (format&0xf000)==0x0000 monitor for streams, stop for samples (format&0xf000)==0x2000 record for streams, loop for samples MODE: This is a CARD32, which is '0', '1', '2' or '3'. 0 ERROR 1 STANDBY 2 AUTOSTANDBY 3 RUNNING Packet Format ------------- init: 4 0 opcode 16 ESDKEY esd-key 4 ENDIAN 'ENDN' or 'NDNE' w 4 BOOLEAN 0 or 1 lock: 4 1 opcode 16 ESDKEY esd-key 4 ENDIAN unused w 4 BOOLEAN 0 or 1 unlock: 4 2 opcode 16 ESDKEY esd-key 4 ENDIAN unused w 4 BOOLEAN 0 or 1 stream-play: 4 3 opcode 4 FORMAT format 4 CARD32 rate 128 ESDNAME name ? ESDSTREAM stream of PCM sound //stream-mon: This protocol is not used for the remote esd. // 4 4 opcode // 4 FORMA format // 4 CARD3 rate // 128 ESDNAME name // w ? ESDSTREAM stream of PCM sound stream-mon: 4 5 opcode 4 FORMAT format 4 CARD32 rate 128 ESDNAME name w ? ESDSTREAM stream of PCM sound sample-cache: 4 6 opcode 4 FORMAT format 4 CARD32 rate 4 n size 128 ESDNAME name w 4 CARD32 sample-id n ARRAY8(n) stream of PCM sound w 4 CARD32 sample-id sample-free: 4 7 opcode 4 CARD32 sample-id w 4 CARD32 sample-id sample-play: 4 8 opcode 4 CARD32 sample-id w 4 CARD32 sample-id sample-loop: 4 9 opcode 4 CARD32 sample-id w 4 CARD32 sample-id sample-stop: 4 10 opcode 4 CARD32 sample-id w 4 CARD32 sample-id sample-kill: 4 11 opcode 4 CARD32 sample-id w 4 CARD32 sample-id standby: 4 12 opcode 16 ESDKEY esd-key 4 ENDIAN unused w 4 BOOLEAN 0 or 1 resume: 4 13 opcode 16 ESDKEY esd-key 4 ENDIAN unused w 4 BOOLEAN 0 or 1 sample-getid: 4 14 opcode 128 ESDNAME name w 4 CARD32 sample-id stream-filter: 4 15 opcode 4 FORMAT format 4 CARD32 rate 128 ESDNAME name w 4 BOOLEAN 0 or 1 server-info: 4 16 opcode w 4 CARD32 version w 4 CARD32 rate w 4 FORMAT format server-all-info: 4 17 opcode w 4 CARD32 version w 4 CARD32 rate w 4 FORMAT format w ? STREAMINFO w ? SAMPLEINFO STREAMINFO: except for last in series w 4 CARD32 id w 16 ESDNAME name w 4 CARD32 rate w 4 CARD32 left-vol-scale w 4 CARD32 right-vol-scale w 4 FORMAT format last in series w 4 CARD32 0 w 32 ARRAY8(32) unused SAMPLEINFO: except for last in series w 4 CARD32 id w 16 ESDNAME name w 4 CARD32 rate w 4 CARD32 left-vol-scale w 4 CARD32 right-vol-scale w 4 FORMAT format w 4 CARD32 sample-length last in series w 4 CARD32 0 w 36 ARRAY8(36) unused //subscribe: undefined // 4 18 opcode //unsubjcribe: undefined // 4 19 opcode stream-pan: 4 20 opcode 4 CARD32 stream-id 4 CARD32 left-scale 4 CARD32 right-scale w 4 BOOLEAN 0 or 1 sample-pan: 4 21 opcode 4 CARD32 sample-id 4 CARD32 left-scale 4 CARD32 right-scale w 4 BOOLEAN 0 or 1 standby-mode: 4 22 opcode 4 0 version w 4 MODE mode w 4 BOOLEAN 0 or 1 latency: 4 23 opcode w 4 CARD32 latency