Subject: [resend] eci_doc for ecasound.el
From: Mario Lang (mlang_AT_delysid.org)
Date: Fri Dec 19 2003 - 15:08:22 EET
Hi.
Kai recently asked me if I could write up some docs for
ecasound.el. I've sent my patch a week ago or so,
and am now resending it to the list in case it got lost.
Index: Documentation/programmers_guide/eci_doc.latex
===================================================================
RCS file: /home/cvspsrv/cvsroot/sound/ecasound/Documentation/programmers_guide/eci_doc.latex,v
retrieving revision 1.15
diff -u -r1.15 eci_doc.latex
--- Documentation/programmers_guide/eci_doc.latex 3 Dec 2003 00:11:54 -0000 1.15
+++ Documentation/programmers_guide/eci_doc.latex 19 Dec 2003 13:07:00 -0000
@@ -586,6 +586,84 @@
$stdout << "Chain operator status: " + e.command("cop-status") + "\n"
\end{verbatim}
+% ----------------------------------------------------------------------
+\subsection{Emacs}
+\subsubsection{Overview}
+The ecasound package comes with an 'Ecasound' library for Emacs included.
+ecasound.el is a implementation of the ECI API for Emacs, as well
+as an interactive interface to Ecasound sessions implemented
+on top of that. Simply use "M-x ecasound RET" to fire up an
+interactive ecasound session.
+
+All Emacs Lisp ECI functions are prefixed with ``eci\-''.
+'ecasound.el' is implemented in a high level manner which means
+that you won't find most of the commands known from libecasoundc like
+last\_string, last\_float, etc.
+Instead of that every call to function "eci-command", which accepts all
+the well known IAM commands, returns ecasound's response in an appropriate type
+automatically.
+If an error occurs, e. g. there's a typo in a command or a file is not found,
+the function returns ``nil''. In all other cases, either an automatically
+converted Lisp value is returned, or ``t'' in the case where there was no
+particular value returned.
+
+Additionally, most of the available IAM commands have their own Emacs Lisp
+function including documentation and possibly a parameter list. All these
+functions are interactive, so you can use them in ecasound-iam-mode simply
+by invoking them via M-x or by pressing an assigned key combination.
+Emacs will prompt you for the required parameters, providing completion
+wherever possible.
+
+As a convention, "eci-command" and its variants do take a buffer or process
+as an optional last argument. If this is ``nil'', the current
+buffer is assumed to be the ecasound session refered to by this call.
+This makes it possible to use several ECI sessions concurrently, dispatching
+on the buffer or process in use.
+
+\subsubsection{Usage}
+\begin{enumerate}
+\item make ecasound.el available in your ``load-path''
+\item (require 'ecasound)
+\item create a buffer with an associated Ecasound session (``eci-init'')
+\item use ``eci\-'' functions with the new buffer
+\end{enumerate}
+
+\subsubsection{Example}
+\begin{verbatim}
+(require 'ecasound)
+
+(defun example (file &optional cutoff-increment session)
+ (unless cutoff-increment (setq cutoff-increment 500.0))
+ (with-current-buffer (or session (eci-init))
+ (eci-cs-add "play_chainsetup")
+ (eci-c-add "1st_chain")
+ (eci-ai-add file)
+ (eci-ao-add "/dev/dsp")
+ (eci-cop-add "-efl:100")
+ (eci-cop-select 1)
+ (eci-copp-select 1)
+ (eci-cs-connect)
+ (eci-start)
+ (sit-for 1)
+ (while (and (string= (eci-engine-status) "running")
+ (<= (eci-get-position) 15))
+ (eci-copp-set (+ cutoff-increment (eci-copp-get)))
+ (sit-for 1))
+ (eci-command "stop")
+ (when (eci-cs-disconnect)
+ (destructuring-bind
+ ((cop n1 (copp n2 val)))
+ (cdr (assoc "1st_chain" (eci-cop-status)))
+ (message "%s %s is now %f" cop copp val)))))
+\end{verbatim}
+
+NOTE: function ``eci-cop-status'' is actually a very high level function
+which already converts the returned information to a nested list
+structure.
+
+For more complex examples of the Emacs Lisp ECI implementation, see function
+``eci-example'', ``ecasound-normalize'' and ``ecasound-signalview'' in
+ecasound.el.
% ----------------------------------------------------------------------
--
CYa,
Mario | Debian Developer <URL:http://debian.org/>
| Get my public key via finger mlang_AT_db.debian.org
| 1024D/7FC1A0854909BCCDBE6C102DDFFC022A6B113E44
This archive was generated by hypermail 2b28 : Fri Dec 19 2003 - 15:03:12 EET