From 6823cecd511e9972a1670fb041c9bb5ad7487b32 Mon Sep 17 00:00:00 2001
From: Olivier Guilyardi <olivier@samalyse.com>
Date: Thu, 26 Nov 2009 17:22:11 +0000
Subject: [PATCH] refactor encode api

---
 encode/api.py | 49 +++++++++++++++++++++++++++++++------------------
 1 file changed, 31 insertions(+), 18 deletions(-)

diff --git a/encode/api.py b/encode/api.py
index 7f77f75..628b1dd 100644
--- a/encode/api.py
+++ b/encode/api.py
@@ -29,6 +29,17 @@ class IEncoder(Interface):
     # from the caller's point of view. However, when implementing the class
     # you'll obviously want to include this extra argument.
 
+    # FIXME: this constructor conflicts with the core component architecture
+    def __init__(output, nchannels, samplerate):
+        """The constructor must always accept the output, nchannels and samplerate 
+        arguments.  It may accepts extra arguments such as bitrate, depth, etc.., 
+        but these must be optionnal, that is have a default value.
+        
+        The output must either be a filepath or a callback function/method for 
+        for the streaming mode. The callback must accept one argument which is 
+        block of binary data.
+        """
+
     def format():
         """Return the encode/encoding format as a short string
         Example: "MP3", "OGG", "AVI", ...
@@ -46,25 +57,26 @@ class IEncoder(Interface):
     def mime_type():
         """Return the mime type corresponding to this encode format"""
 
-    def process(source, metadata, options=None):
-        """Perform the encoding process and stream the result as a generator.
-
-        source is a raw audio stream coming from a decoder.
-
-        metadata is a tuple containing tuples for each descriptor return by
+    def set_metadata(metadata):
+        """metadata is a tuple containing tuples for each descriptor return by
         the dc.Ressource of the item, in the model order :
-        ((name1, value1),(name2, value2),(name1, value3), ...)
-
-        The returned file path is not meant to be permanent in any way, it
-        should be considered temporary/volatile by the caller.
-
-        It is highly recommended that encode drivers implement some sort of
-        cache instead of re-encoding each time process() is called.
-
-        It should be possible to make subsequent calls to process() with
-        different items, using the same driver instance.
-        """
-
+        ((name1, value1),(name2, value2),(name1, value3), ...)"""
+
+    def update():
+        """Updates the metadata into the file passed as the output argument
+           to the constructor. This method can't be called in streaming
+           mode."""
+
+    def process(frames):
+        """Encode the frames passed as a numpy array, where columns are channels.
+        
+           In streaming mode the callback passed to the constructor is called whenever
+           a block of encoded data is ready."""
+
+    def finish():
+        """Flush the encoded data and close the output file/stream. Calling this method
+        may cause the streaming callback to be called if in streaming mode."""
+  
 class EncodeProcessError(TimeSideError):
 
     def __init__(self, message, command, subprocess):
@@ -80,3 +92,4 @@ class EncodeProcessError(TimeSideError):
         return "%s ; command: %s; error: %s" % (self.message,
                                                 self.command,
                                                 error)
+
-- 
2.39.5