1 files changed, 101 insertions, 0 deletions
diff --git a/debian/transcode/transcode-1.1.7/docs/tech/clone.txt b/debian/transcode/transcode-1.1.7/docs/tech/clone.txt
new file mode 100644
index 00000000..fa8ba9d1
--- /dev/null
+++ b/debian/transcode/transcode-1.1.7/docs/tech/clone.txt
@@ -0,0 +1,101 @@
+----------------------------------------------------
+More accurate and up-to-date information is in /docs/architecture.txt
+----------------------------------------------------
+
+HOWTO clone frames
+
+I want to contribute a quick how-to how to use the new attribute
+TC_FRAME_IS_CLONED.
+
+I have written two filters tc_video and tc_audio as an
+demonstration example of the clone flag doing actually something
+useful. These filters telecine a NTSC_FILM to NTSC_VIDEO
+(23.9->29.9 fps) for video and audio. The input material must be
+in 23.9 fps or weird results come out. Of course, you can use
+ivtc+decimate to reverse the process and restore the original
+video :)
+
+The best documentation is (as always) the source but let me
+summarize my experience.
+
+A filter can clone (duplicate) a frame by setting the clone flag
+to a frame by
+  ptr->attributes |= TC_FRAME_IS_CLONED;
+
+The encoder then deletes the flag and sets another flag named
+TC_FRAME_WAS_CLONED. This is necessary for the filter because
+frame IDs never get incremented.
+
+The filter has to live in the TC_POST_M_PROCESS or in the
+TC_POST_S_PROCESS (synchronous) slot for this to work and its
+quite a difference between TC_POST_M_PROCESS and TC_POST_S_PROCESS
+
+TC_POST_M_PROCESS:
+  The filter can set the the clone flag which causes the frame
+  to get encoded twice. The filter WON'T see the frame again, so
+  it cannot make modifications to the frame. This is what the
+  demo filter_clone uses.
+
+  import -> .. -> filter (set_clone) -> encoder (frame)-,
+                                     /                  /
+                                     \______<<<________/
+
+TC_POST_S_PROCESS:
+  The filter can set the clone flag which causes the frame to
+  get encoded and run through the filter again with the
+  was_cloned flag set.  The filter can now check if this frame
+  already was cloned and not clone it again. This is very handy
+  when doing modulo insertions of frames.
+
+  import -> .. -> filter (if !was_cloned  -> encoder (frame)-,
+               /          then set_clone)                   /
+               \_________<<<________________<<<____________/
+
+
+Definitions:
+The frame ID never gets incremented to reflect the count of
+cloned frames. If the filter decides to clone a frame, it gets the
+frame back with the same ID but with TC_FRAME_WAS_CLONED set, so
+its easy to distinguish between the frame with the original ID
+and the duplicated ID.
+
+Limitations/Bugs:
+- It is not possible to rerun the frame through the complete
+  filter pipeline. TC_POST_S_PROCESS is the most far away point
+  the frame can get back.
+
+- transcode's encoding frame counter is wrong, but the final
+  message, ie
+  [transcode] encoded 331 frames (0 dropped), clip length  11.04 s
+  is correct.
+
+Notes:
+TC_FRAME_WAS_CLONED is introduced in this patch and is not
+available in earlier transcode versions.
+
+Notes on the included filters:
+The tc_video filter is pretty straight forward, doing a normal
+telecine. Thanks to Thanassis Tsiodras who explained very
+precise what telecine and what inverse telecine is. The code is
+commented to show its work flow and workings.
+
+The tc_audio filter is a bit trickier, because the audio frames
+have to get "repackaged". The audio import bufsize is tweaked to
+read the frames in chunks suitable for 23.9 fps and the filter
+then moves them back and forth to repackage them suitable for
+29.9 fps. Considering this example.
+
+  Import: 48000,16,2 @ 23.9 fps -> bufsize = 8008
+  export: 48000,16,2 @ 29.9 fps -> bufsize = 6408
+
+  The filter does a conversion from 4 frames * 8008 to
+  5 frames * 6408
+
+No data is added or removed.
+
+I think this feature is now pretty usable so start hacking on
+frame rate conversion filters :)
+
+Version 0.1
+
+2002 Tilmann Bitterberg <[email protected]>