[svn-commits] branch file/coremedia - r7325 /team/file/coremedia/doc/README.coremedia

[svn-commits at lists.digium.com]

Author: file
Date: Sun Dec  4 00:18:01 2005
New Revision: 7325

URL: http://svn.digium.com/view/asterisk?rev=7325&view=rev
Log:
Add a small document on what coremedia is, my ideas behind it, what stuff is for

Added:
    team/file/coremedia/doc/README.coremedia

Added: team/file/coremedia/doc/README.coremedia
URL: http://svn.digium.com/view/asterisk/team/file/coremedia/doc/README.coremedia?rev=7325&view=auto
==============================================================================
--- team/file/coremedia/doc/README.coremedia (added)
+++ team/file/coremedia/doc/README.coremedia Sun Dec  4 00:18:01 2005
@@ -1,0 +1,41 @@
+Coremedia is a new concept for the media/translation/rtp payload core inside of Asterisk. It is designed to be totally dynamic in that
+a codec does not have to have an already existing tie in Asterisk to be loaded and utilized. It consists of 5 primary concepts:
+
+--- Coremedia Entry ---
+
+An entry is the base information on a codec. It does not have to contain a pointer to either an encoder or decoder. It does need
+to have a unique name, and sample size however. Optional options are bitrate and old Asterisk format. When the entry is added to the
+internal linked list a unique subclass integer is generated for usage in the internal asterisk frames. The subclass can then be used
+to find the exact entry.
+
+The idea behind entries is that you don't have to have the encoder or decoder for a codec to make it's presence known inside of Asterisk.
+As well in order to use a codec all you need to know is the internal name, bitrate, and sample size. You can then just get a pointer
+to the entry based on that and pass it around. If something needs the encoder or decoder for the entry, it's just a pointer in the
+structure.
+
+--- Coremedia Translator and Translation Core ---
+
+A translator is the actual encoding/decoding portion of an entry. These consist of a function to create a new codec instance, a function
+to take a frame in, a function to get a frame out, and a function to destroy the codec instance. Encoding translators take in signed linear
+as their source, and decoding translators output signed linear. Translators are tied to their corresponding entry during loading of an entry
+or afterwards using the linking API calls.
+
+--- Coremedia Shims ---
+
+Shims allow any application to inject a callback into the translation path of a call so they can modify, or copy the audio. If a translation path
+does not exist when a shim is added to a call, one is setup to read and write through signed linear. If no encoder or decoder is available then
+the Shim addition to the channel fails - as a translator path is required. This ensures that shims always get the same
+type of audio - signed linear. Shims do not need to register themselves. They are passed to the shimmy API call from the originating
+application.
+
+--- Coremedia RTP ---
+
+An RTP instance consists of the entry name, SDP name, sample size, and payload id. If a payload id is not specified, a dynamic one is allocated
+per the RFC. RTP instances are kept in an array using their payload id for quicker lookup.
+
+--- Coremedia Handle ---
+
+Handles are wrappers around entries. They allow you to easily create a linked list of available codecs for example. API calls are
+then available to do comparisons, or to combine two handles to get the supported codecs by both. Codec preference is determined by
+order in the linked list. The most preferred is at the head of the list while the least preferred is at the end.
+Practical use would be for channel drivers for capabilities of users, peers, remote party, etc.