1EsounD Protocol (Draft) 2Author: ymnk<ymnk@jcraft.com> 3Data: 2000-10-02 4=============== 5 6Introduction 7------------ 8This document describes the protocol in EsounD system. 9Unfortunately, any formal description about EsounD had not existed. 10So the author has tried to read the source code of EsounD and written this 11document. The author is also the author of JEsd, which is a re-implementation 12of EsounD in pure Java and this document is based on his knowledge, 13which had gotten in hacking JEsd. 14 15 16Connection Setup 17---------------- 18The esd will wait for the TCP connection requests from EsounD compatible 19applications. In the default, esd will listen to the TCP port 16001. 20The client must send an initial byte of data to be authorized them-self 21and to identify the byte order to be employed. 22For authorization, client must send 'esd-key', which is a 16 byte data. 23For endian-ness, client must send a 4 byte data. 24If esd does not detect any error, '1' will be sent back and 25'0' will be sent back in error. 26 27Requests 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 49Syntactic Conventions 50-------------------- 51All numbers are in decimal, unless prefixed with '0x', in which case 52they are in hexadecimal(base 16). 53 54The general syntax used to describe data packets is: 55 Name: 56 encoded-form 57 ... 58 encoded-form 59 60For components described in the protocol descriptions as: 61 name: TYPE 62 w name: TYPE 63the encode-form are: 64 N TYPE name 65and 66w N TYPE name 67N is the number of bytes in the data stream, and TYPE is the interpretation 68of those bytes. For example, 69 result: BOOLEAN 70becomes: 71 4 BOOLEAN result 72 73For components with a static numeric value the encode-form is: 74 N value name 75The value is always interpreted as a N-byte unsigned integer. 76 77 78Data 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 108Packet 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 223STREAMINFO: 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 236SAMPLEINFO: 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 280