[farsight2/master] Import design doc for codec nego from fs1

[Olivier Crête]

---
 docs/codec-parameters.txt |   84 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 84 insertions(+), 0 deletions(-)
 create mode 100644 docs/codec-parameters.txt

diff --git a/docs/codec-parameters.txt b/docs/codec-parameters.txt
new file mode 100644
index 0000000..4eb94a0
--- /dev/null
+++ b/docs/codec-parameters.txt
@@ -0,0 +1,84 @@
+List of possible offers is gathered from rtp caps 
+- fixed paremeters are copied as-is, others are not included
+This is the global list of CodecBlueprints. It is loaded once and never changes.
+
+For each RTP stream:
+
+The application can pass a list of FsCodec with its desired
+properties, the same codec can be there more than once if the app
+desires to have the same codec many times with different properties. This
+list of FsCodec can contain codec ids (to force specific codecs into
+specific ids), otherwise if the codec id is < 0 or > 127, a dynamic
+codec id will be attributed... To remove a codec from the list of
+offered codecs, it would be preferable to have a flag in the codec list.
+
+For each loaded codec (aka CodecBlueprint), we check if there is one
+or more compatible (as in gstcaps comptatible) section in the passed
+list. If there are some, we replace the autogenerated offered codec
+for that codec by ones which correspond to the union of the fixed
+parameters from the config file and element... This makes the 
+local_codec_association table.  From there we generate the
+local_codecs list that points to this local_codecs_association table,
+this is valid until a new list of FsCodecs is passed. The
+codec_associations table is initialized as a copy of local_codec_associations.
+
+For SDP codec negociation: since there are codec-specific things, we
+will use a table of tuples (media_type, encoding-name, function) where
+the function is: 
+FsCodec *sdp_codec_negotiate(GstCaps *rtpcaps, FsCodec *mycodec, FsCodec *hiscodec); 
+This function will return the negociated FsCodec or NULL if its
+impossible to reconcile the remote and the local one. It should always
+return something when being fed a valid reply from our offer. And we
+will also have generic function that check if everything present in
+both is identical.
+
+We store the negociated codecs in codec_associations. From these
+negociated FsCodecs, we'll generate Caps to be used for the
+pt_caps_table. We always accept the remote PTs even if they dont match
+the ones we have locally (but in this case we print a big warning). If
+there was an offered codec that was rejected, we remove the codec from
+the codec_associations, but we keep a NULL entry so that the PT is not
+re-used. If a remote PT was rejected, we also store a NULL in
+codec_associations to prevent the re-use of that PT.
+
+If the user wants to initiate a new negociation, he can optionally
+give farsight a new list of FsCodec. This list will be merged into
+local_codec_associations, while not re-using already used PTs by
+looking at codec_associations. Using the same process used the first
+time.  Then the user can get the list of local codecs again. The user
+then passes a new list of remote_codecs, codec_associations is
+regenerated from local_codec_associations and remote_codecs, while
+keeping NULLs in the place of old codecs to make sure the PTs are not
+re-used.
+
+If the remote end initiates a new codec negociation, we get a new
+list of remote codecs, and we merge it into a new codec_associations,
+if its not empty, we replace the old one with it and set_remote_codec
+succeeds. If its empty, set_remote_codec fails and we keep the old
+codec_associations. get_codec_intersection which will return a
+list of codecs from the codec_associations table.
+
+
+TODO:
+
+- Generate the local_codec_associations table using passed list (DONE)
+- Build local_codecs from local_codec_associations (DONE)
+- Add codec negociation functions (generic and specific) (DONE)
+- Use new codec negociation functions to do SDP negociation on
+  set_remote_codecs (DONE)
+- Generate pt_caps_table with negociated properties (DONE)
+- Make get_codec_intersection return the list of negociation codes
+  from codec_associations (DONE)
+
+- Add helper to build list of fscodecs from a file (DONE)
+- Add API function to pass desired Codecs and merged them into
+  local_codec_associations (with tp/s-e stuff?)
+
+
+- Add a function to validate user passed FsCodec based on rtp caps
+
+PROBLEMS:
+
+- What about atomic codec/port/ip changes (create new streams)
+- How to keep the order in codec_associations (it is a hash
+  table).. Create a list to go with it, that points to the same structures
-- 
1.5.6.5