 
 ;; Sending a synth-id of -1 lets the server choose an ID
 (defn node
-  "Instantiate a synth node on the audio server."
+  "Instantiate a synth node on the audio server.  Takes the synth name and a set of 
+  argument name/value pairs.  Optionally use :target <node/group-id> and :position <pos>
+  to specify where the node should be located.  The position can be one of :head, :tail,
+  :before-node, :after-node, or :replace-node.
+
+  (node \"foo\")
+  (node \"foo\" :pitch 60)
+  (node \"foo\" :pitch 60 :target 0)
+  (node \"foo\" :pitch 60 :target 2 :position :tail)
+  "
   [synth-name & args]
   {:pre [(connected?)]}
   (let [id (alloc-id :node)

(defonce server*        (ref nil))
(defonce status*        (ref :no-audio))
(defonce synths*        (ref nil))

(defonce sc-world* (ref nil))

;TODO: Figure out the real limits...  These are total guesses, but
; it should be plenty.
(def MAX-GROUPS 256)

(def GROUP-BITS (BitSet. MAX-GROUPS))
(.set GROUP-BITS 0) ; Group 0 is the persistent root group

; Server limits
(defonce MAX-NODES 1024)

(defn buffer? [buf]
  (= (type buf) ::buffer))

(defn- buf-or-id [b]
  (cond
    (buffer? b) (:id b)
    (number? b) b
    :default (throw (Exception. "Not a valid buffer: " b))))

(defn buffer-free
  "Free an audio buffer and the memory it was consuming."
  [buf]
  (free-id :audio-buffer (:id buf))
  (snd "/b_free" (:id buf)))

