initial version of videotimeline doc..

_manual/23_video-timeline.html

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Video Timeline and Monitoring
+---                        
+
+<h2>Introduction</h2>
+<p>
+The integration of a video timeline and video monitoring into Ardour 3.x allows for convenient audio mixing and editing to video ie soundtracks, music videos, TV post production etc.
+</p>
+  
+
+<p>
+Ardour 3.x sessions provide facilities to:
+</p>
+<ul>
+<li>Import a single video and optionally extract the soundtrack from it.
+</li>
+<li>Provide a Video-monitor window, or full-screen display, of the imported video in sync with any of the available ardour timecode sources.
+</li>
+<li>Display a frame-by-frame (thumbnail) timeline of the video.
+</li>
+<li>time-offset the video
+</li>
+<li><em>Lock</em> audio-regions to the video: Move audio-regions with the video at video-frame granularity.
+</li>
+<li>Export the video, cut start/end, add blank frames and/or mux it with the soundtrack of the current-session.
+</li>
+</ul>
+
+<p>
+Furthermore setup is modular and can be configured in different ways, including:
+</p>
+<ul>
+<li>One machine: all video decoding, video monitoring and Ardour audio
+</li>
+<li>Two machines: separate video-monitor and Ardour
+</li>
+<li>Three machines: separate video-server (for timeline decoding and file-archive), dedicated video-monitor and Ardour
+</li>
+</ul>
+
+<p>
+Ardour does <strong>not</strong> :
+</p>
+<ul>
+<li>allow for more than one video to be loaded at a time.
+</li>
+<li>provide video editing capabilities
+</li>
+</ul>
+
+<h2>Subtopics</h2>
+
+{% children %}

_manual/23_video-timeline/01_setup.html

@@ -0,0 +1,85 @@
+---
+layout: default
+title: Video Timeline Setup
+---
+
+<p>
+Ardour 3.x requires no configuration if you intend to run everything on a single machine, and if you acquired Ardour 3.x from <a href="http://www.ardour.org" title="http://www.ardour.org"  rel="nofollow">http://www.ardour.org</a>, everything is pre-configured and included with the download/install.
+</p>
+
+
+<h2>Single Machine</h2>
+
+<p>
+If you compile Ardour 3.x from source, or have installed it from a 3rd party, additional tools will need to be installed.
+</p>
+
+<p>
+There are three separate standalone tools involved which are used by Ardour 3.x to provide video facilities.
+</p>
+<ul>
+<li>xjadeo – the video monitor window<a href="http://xjadeo.sf.net" title="http://xjadeo.sf.net"  rel="nofollow">http://xjadeo.sf.net</a>
+</li>
+<li>harvid – a video decoder used for the thumbnail timeline <a href="http://x42.github.com/harvid/" title="http://x42.github.com/harvid/"  rel="nofollow">http://x42.github.com/harvid/</a>
+</li>
+<li>ffmpeg, ffprobe – used to import/export video, extract soundtracks and query video information <a href="http://ffmpeg.org" title="http://ffmpeg.org"  rel="nofollow">http://ffmpeg.org</a>
+</li>
+</ul>
+
+<p>
+Ardour 3.x requires xjadeo &gt;= version 0.6.4, harvid &gt;= version 0.7.0 and ffmpeg == 1.2.
+</p>
+
+<p>
+The ardour-dev team is <em>in control</em> of the first two applications. ffmpeg can be a bit of a problem.
+To avoid conflicts with distribution packages, ardour looks for <code>ffmpeg_harvid</code> and <code>ffprobe_harvid</code>.
+</p>
+
+<p>
+All four applications need to be found in <code>$PATH</code> (e.g. <code>$HOME/bin</code> or <code>/usr/local/bin</code>). For convenience the binary releases of harvid include ffmpeg_harvid and ffprobe_harvid, but if your distribution provides suitable ffmpeg commands you can also just create a symbolic link from ffmpeg → ffmpeg_harvid and ffprobe → ffprobe_harvid.
+</p>
+
+<p>
+Binary releases are available from ardour.org as well as an installer script: <a href="https://github.com/Ardour/ardour/blob/master/tools/videotimeline/install_video_tools.sh" title="https://github.com/Ardour/ardour/blob/master/tools/videotimeline/install_video_tools.sh"  rel="nofollow">install_video_tools.sh</a>.
+</p>
+
+<p>
+You can run it directly as:
+</p>
+<pre class="code">sh -c &quot;$(curl -s -L http://git.io/tVUCkw)&quot;</pre>
+
+
+<h2>Studio Setup</h2>
+
+<p>
+Please read the info in the previous section to familiarize yourself with the tools involved.
+Setting up a proper A/V post-production studio can be a complicated task. As much as we streamline and simply the <em>single machine</em> setup, the studio-setup is focused on modularity.
+</p>
+
+<p>
+<em>TODO</em>
+</p>
+<ul>
+<li>Synchronization ardour → video-display-box should be accomplished by external means jack-transport(netjack), MTC, LTC (<acronym title="Open Sound Control - &quot;postmodern MIDI&quot;">OSC</acronym> and/or ssh-pipe work but introduce additional latency + jitter)
+</li>
+</ul>
+<ul>
+<li>Ardour launches <code>XJREMOTE</code> (environment variable, default &#039;xjremote&#039; which comes with xjadeo also on OSX).
+</li>
+</ul>
+<ul>
+<li>Either use a custom shell script that ssh&#039;es into the remote box and launches/controls xjadeo there, selects the sync-source and passes though communication between ardour ⇔ xjadeo via ssh (xjadeo is launched stopped with the session).
+</li>
+</ul>
+<ul>
+<li>..or override xjremote&#039;s behavior – instead of  IPC with a local running xjadeo-process, using <acronym title="Open Sound Control - &quot;postmodern MIDI&quot;">OSC</acronym> for example. xjadeo would run permanently and ardour will just tell it to load files and set offsets via <acronym title="Open Sound Control - &quot;postmodern MIDI&quot;">OSC</acronym>. see <a href="http://xjadeo.git.sourceforge.net/git/gitweb.cgi?p=xjadeo/xjadeo;a=blob_plain;f=contrib/xjremote-osc" title="http://xjadeo.git.sourceforge.net/git/gitweb.cgi?p=xjadeo/xjadeo;a=blob_plain;f=contrib/xjremote-osc"  rel="nofollow">xjremote-osc</a> example script.
+</li>
+</ul>
+<ul>
+<li>If the video server runs remotely, Ardour needs to be configured in Ardour &gt; Preference &gt; Video (hostname of the video-server).
+</li>
+</ul>
+
+<p>
+Ideally the machines have a common shared folder (NFS or similar).  Ardour&#039;s import (audio-extract) and export (mux) functionality depends on having access to the video file.  Also ardour video-import transcodes the file into a suitable proxy-format that allows reliable seeking to any frame…
+</p>

_manual/23_video-timeline/02_transcoding_formats_codecs.html

@@ -0,0 +1,37 @@
+---
+layout: default
+title: Transcoding, Formats & Codecs
+---
+
+<p>
+A short primer on video-files, formats and codecs – because it is often cause for confusion:
+</p>
+
+<p>
+A video file is a <em>container</em>. It usually contains one video-track and one or more audio-tracks.
+</p>
+
+<p>
+How these tracks are stored in the file is defined by the <strong>file-format</strong>. Common formats are avi, mov, ogg, mkv, mpeg, mpeg-ts, mp4, flv, vob
+</p>
+
+<p>
+Each of the tracks by itself in <em>encoded</em> - using a Codec. Common Video-Codecs are h264, mpeg2, mpeg4, theora, mjpeg, wmv3. Audio-Codecs: mp2, mp3, dts, aac, wav/pcm.
+</p>
+
+<p>
+Not all codecs can be packed into a given format. For example the &#039;mpeg&#039; format is limited to mpeg2, mpeg4 and mp3 codecs (not entirely true) and generally naming conventions uses for format and codecs are cause for a lot of confusion. DVDs do have stringent limitations…
+</p>
+
+<p>
+The export dialog includes presets for common format &amp; codec combinations (such as DVD, web-video,..). If in doubt use one of the presets.
+</p>
+
+<p>
+All in all it is a very wide and deep field. Suffice there are different uses for different codecs.
+When importing a video into ardour, it will be <em>transcoded</em> (transcoding: change from one format and codec to another) to avi/mjpeg for internal use (this allows reliable seeking to frames at low CPU cost - the file-size will increase, but hard-disks are large and fast).
+</p>
+
+<p>
+As last note: Every time a video is transcoded the quality gets worse. Hence for the final mastering/muxing process always to back to the original source of the video.
+</p>

_manual/23_video-timeline/03_operations.html

@@ -0,0 +1,109 @@
+---
+layout: default
+title: Workflow & Operations
+---
+
+<ul>
+<li>Session &gt; Open Video - add/replace a video to/on the timeline
+</li>
+<li>Window &gt; View Monitor  open/close external video monitor window
+</li>
+<li>View &gt; Video Monitor &gt; … settings of the video monitor
+</li>
+<li>Session &gt; Export &gt; Video
+</li>
+</ul>
+<ul>
+<li>Drag the video in the timeline - right click and choose &#039;lock&#039; to prevent accidental drags
+</li>
+<li>Audio-Region &gt; context-menu &gt; Position &gt; Lock to video – audio-region(s) are moved along with the video.
+</li>
+</ul>
+
+
+<h2>Adding Video</h2>
+
+<p>
+Adding video is a two-step process.
+</p>
+<ol>
+<li>Select video file
+</li>
+<li>Choose import-mode and optionally select an audio-track to extract
+</li>
+</ol>
+
+<p>
+<br/>
+
+</p>
+
+<p>
+<img src="/files/a3/ardour/a3_video_open.png" class="medialeft" alt="video-open-dialog" width="300" />
+</p>
+
+<p>
+The first step is rather straight forward: The panel on the right side allows to seek through the video and displays basic file information. It is also useful to check if the video format/codec is supported:
+</p>
+
+<p>
+<br/>
+
+</p>
+
+<p>
+<img src="/files/a3/a3_video_import.png" alt="Video Import Dialog" width="300" />
+</p>
+
+<p>
+The second step analyzes the video file in more detail and offers import options:
+</p>
+<ul>
+<li><strong>Import/Transcode to Session</strong>. This is the default. The video will be imported in a suitable video-format/codec for the timeline and video monitor and saved inside the session folder. A location different than the session folder can also be chosen (extrnal disk, network storage of the video server on a different machine…).
+</li>
+<li><strong>Reference from Current Location</strong>. Only useful for opening files that were previously encoded (are already in a good format/codec) use with care.
+</li>
+<li><strong>Do not Import Video</strong> - useful for extracting audio only.
+</li>
+</ul>
+
+<p>
+By default the video is imported using the original width/height. If it is a large video (e.g. full-HD) it will make sense to scale it down to lighten CPU and disk I/O required to play it. For editing sound-tracks, a small representation is usually sufficient. The default bitrate is set to use 0.7 bits per pixel. Some key values: the average DVD medium uses 5000kbit/sec.
+</p>
+
+<h2>Working with A/V</h2>
+
+<p>
+<img src="/files/a3/a3_videotimeline.png" alt="Video Timeline" width="600" />
+</p>
+
+<p>
+Well now,..
+</p>
+
+
+<h2>Exporting Video</h2>
+
+<p>
+<img src="/files/a3/a3_video_export.png" alt="Video Export Dialog" width="300" />
+</p>
+
+<p>
+The video-export will take audio from the current Ardour session and multiplex it with a video-file.
+</p>
+
+<p>
+By default the video file that is displayed on the timeline is used as video-source. This may not be the best option but is usually sufficient for dailies and demo snapshots. For high quality exports the original file (before it was imported in the timeline) should be used. Any existing audio tracks on the video-file are stripped.
+</p>
+
+<p>
+The soundtrack of the video is taken from an audio-export of ardour&#039;s master bus.
+</p>
+
+<p>
+The range selection allows to cut or extend the video. If the session is longer than the video duration, black frames are prefixed or appended to the video. If Ardour&#039;s session range is shorter the video will be cut accordingly.
+</p>
+
+<p>
+Audio Samplerate and Normalize Audio are options for Ardour&#039;s audio exporter. The remaining settings are options that are directly passed on to ffmpeg.
+</p>