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