manual/include/timecode-generators-and-slaves.html

<p>
  Ardour supports three common timecode formats:
  <abbr title="Linear/Longitudinal Time Code"><dfn>LTC</dfn></abbr>,
  <abbr title="MIDI Time Code"><dfn>MTC</dfn></abbr>, and
  <dfn>MIDI Clock</dfn>, as well as 
  <dfn>JACK-transport</dfn>, a JACK-specific timecode implementation.
</p>
<p>
  Ardour can generate timecode and thus act as timecode <dfn>master</dfn>, 
  providing timecode information to other applications. Ardour can also be 
  <dfn>slaved</dfn> to some external source in which case the playhead 
  follows the incoming timecode.<br>
  Combining the timecode slave and generator modes, Ardour can also 
  <dfn>translate</dfn> timecode. e.g create LTC timecode from incoming MTC.
</p>


<h2>Ardour Timecode Configuration</h2>

<p>
  Each Ardour session has a specific timecode frames-per-second setting which 
  is configured in <kbd class="menu">session &gt; properties &gt;
  timecode</kbd>. The selected timecode affects the timecoderuler in the main 
  window as well as the clock itself.
</p>

<p>
  Note that some timecode formats do not support all of Ardour's available 
  fps settings. MTC is limited to 24, 25, 29.97 and 30 fps.
</p>

<p>
  The video pull-up modes change the effective samplerate of Ardour to allow
  for changing a film soundtrack from one frame rate to another. The concept is 
  beyond the scope of this manual, but Wikipedia's entry on 
  <a href="http://en.wikipedia.org/wiki/Telecine">Telecine</a> 
  may get you started.
</p>

<h2>Ardour Timecode Generator Configuration</h2>

<p>
  This is pretty straightforward: simply turn it on. The MTC and MIDI-Clock 
  generator do not have any options. The LTC generator has a configurable
  output level. JACK-transport cannot be <em>generated</em>. Jack itself is 
  always synced to its own cycle and cannot do varispeed&mdash;it will
  always be synced to a hardware clock or another JACK master.
</p>

<p>
  The relevant settings for timecode generator can be found in 
  <kbd class="menu">Edit &gt; Preferences &gt; MIDI Preferences</kbd> (for MTC,
  MC) and
  <kbd class="menu">Edit &gt; Preferences &gt; Transport Preferences</kbd>
  (for LTC).
</p>

<p>
  The timecode is sent to jack-ports <code>ardour:MTC out</code>, 
  <code>ardour:MIDI clock out</code> and <code>ardour:LTC-out</code>. Multiple 
  generators can be active simultaneously.
</p>

<p class="note">
  Note that, as of Jan 2014, only the LTC generator supports latency 
  compensation. This is due to the fact the Ardour MIDI ports are not 
  yet latency compensated.
</p>

<p>
  In <kbd class="menu">Session &gt; Properties</kbd>, it is possible to 
  define an offset between Ardour's internal time and the timecode sent. 
  Currently only the LTC generator honors this offset.
</p>

<p>
  Both LTC and MTC are limited to 30&nbsp;fps. Using frame rates larger 
  than that will disable the generator. In both cases also only 24, 25, 
  29.97df (drop-frame) and 30&nbsp;fps are well defined by specifications (such as 
  SMPTE-12M, EU and the MIDI standard).
</p>

<h3>MTC Generator</h3>
<p>
  The <dfn>MTC generator</dfn> has no options. Ardour sends full MTC 
  frames whenever the transport is relocated or changes state (start/stop). 
  MTC <dfn>quarter frames</dfn> are sent when the transport is rolling and 
  the transport speed is within 93% and 107%.
</p>

<h3>LTC Generator</h3>
<p>
  The level of the <dfn>LTC generator</dfn> output signal can be configured 
  in in the <kbd class="menu">Preferences &gt; Transport</kbd> dialog. By 
  default it is set to -18&nbsp;dBFS, which corresponds to 0dBu in an EBU 
  calibrated system.
</p>
<p>
  The LTC generator has an additional option to keep sending timecode even 
  when the transport is stopped. This mode is intended to drive analog tape 
  machines which unspool the tape if no LTC timecode is received.
</p>
<p>
  LTC is send regardless of Ardour's transport speed. It is accurately 
  generated even for very slow speeds (&lt;5%) and only limited by the 
  soundcard's sampling-rate and filter (see 
  <a
  href="http://en.wikipedia.org/wiki/Gibbs_phenomenon#Signal_processing_explanation">Gibbs phenomenon</a>) 
  for high speeds.
</p>


<h2>Ardour Slave Configuration</h2>
<p> 
  The timecode source can be switched with the button just right of 
  Ardour's main clock. By default it is set to <kbd
  class="menu">Internal</kbd> in which case Ardour will ignore any external 
  timecode. The button allows to toggle between Internal and the configured 
  timecode source which is chosen in <kbd class="menu">Edit &gt; Preferences 
  &gt; Transport</kbd>.
</p>
<p>
  When Ardour is <dfn>chasing</dfn> (synchronizing to) an external timecode 
  source, the following cases need to be distinguished:
</p>
<ol>
  <li>the timecode source shares the clock</li>
  <li>the timecode source is independent (no wordclock sync)</li>
</ol>
<p>and</p>
<ol>
  <li>the timecode source uses the same FPS setting as Ardour</li>
  <li>the timecode source runs at different frames-per-second</li>
</ol>
<p>
  In both cases the first option is preferred: clock sync + same FPS setting.
</p>

<h3>Frames-per-second</h3>
<p>
  If the frames-per-second do not match, Ardour can either re-calculate 
  and map the frames, or the configured FPS (<kbd class="menu">Session &gt;
  Properties</kbd>) can be changed automatically while the slave is active. 
  The behavior is configured with the checkbox <kbd class="option">Edit 
  &gt; Preferences &gt; Transport &gt; Match session video frame rate to 
  external timecode</kbd>.
</p>
<p>
  When enabled, the session video frame rate will be changed to match that 
  of the selected external timecode source. When disabled, the session video 
  frame rate will not be changed to match that of the selected external 
  timecode source. Instead the frame rate indication in the main clock will 
  flash red, and Ardour will convert between the external timecode standard 
  and the session standard.
</p>
<p class="warning">
  29.97 drop-frame timecode is another corner case. While the SMPTE 12M-1999 
  specifies 29.97df as 30000/1001 frames per second, not all hardware devices 
  follow that standard. The checkbox 
  <kbd class="option">Lock to 29.9700 fps instead of 30000/1001</kbd> allows 
  to use a compatibility mode for those devices.<br>
  When enabled, the external timecode source is assumed to use 29.970000 fps 
  instead of 30000/1001. SMPTE 12M-1999 specifies 29.97df as 30000/1001. The 
  <abbr title="specification">spec</abbr> further mentions that drop-frame 
  timecode has an accumulated error of -86&nbsp;ms over a 24-hour period. 
  Drop-frame timecode would compensate exactly for a NTSC color frame rate 
  of 30 * 0.9990 (ie 29.970000). That is <em>not</em> the actual rate. However, 
  some vendors use that rate&mdash;despite it being against the
  specs&mdash;because the variant of using exactly 29.97 fps yields zero
  timecode drift.
</p>

<h3>Clock Sync Lock</h3>
<p>
  As described in the 
  <a href="http://manual.ardour.org/synchronization/on-clock-and-time/">On Clock and Time</a>
  chapter, timecode and clock are independent. If the external timecode 
  source is not in sample-sync with the audio hardware (and JACK), Ardour 
  needs to run at varispeed to adjust for the discrepancy.
</p>
<p>
  The checkbox <kbd class="option">External timecode is sync locked</kbd> 
  allows to select the behavior according to your setup. When enabled, it 
  indicates that the selected external timecode source shares sync (Black 
  &amp; Burst, Wordclock, etc) with the audio interface.
</p>
<p>
  In other words: if enabled, Ardour will only perform initial 
  synchronization and keep playing at speed 1.0 instead of vari-speed 
  adjusting to compensate for drift.
</p>
<p class="note">
  Note that vari-speed is unavailable when recording in Ardour, and all 
  tracking happens at speed 1.0. So if you want to record in sync with 
  external timecode it must be sample-locked or it will drift over time.
</p>

<h3>MIDI Clock</h3>
<p>
  <dfn>MIDI Clock</dfn> is not a timecode format but tempo-based time. The 
  absolute reference point is expressed as beats-per-minute and Bar, Beat 
  and Tick. There is no concept of sample-locking for MIDI clock signals. 
  Ardour will vari-speed if necessary to chase the incoming signal.
</p>
<p>
  Note that the MIDI Clock source must be connected to the 
  <code>ardour:MIDI clock in</code> port.
</p>

<h3>LTC&mdash;Linear Timecode</h3>
<p>
  The <dfn>LTC</dfn> slave decodes an incoming LTC signal on a JACK audio 
  port. It will auto-detect the frame rate and start locking to the signal
   once two consecutive LTC frames have been received.
</p>
<p>
  The incoming timecode signal needs to arrive at the 
  <code>ardour:LTC-in</code> port. Port-connections are restored for each 
  session and the preference dialog offers an option to select it for all 
  sessions.
</p>
<p>
  Ardour's transport is aligned to LTC-frame start/end positions according 
  to the SMPTE 12M-1999 specification, which means that the first bit of an 
  LTC-Frame is aligned to different Lines of a Video-Frame, depending on the 
  TV standard used. Only for Film (24fps) does the LTC-Frame directly match 
  the video Frame boundaries.
</p>

<img src="/images/ltc-transport-alignment.png"  title="LTC frame alignment" alt="LTC frame alignment"/>
<p><em>Figure: LTC frame alignment for the 525/60 TV standard</em></p>

<p>
  Ardour supports vari-speed and backwards playback but will only follow 
  speed changes if the <kbd class="optoff">sync locked</kbd> option is 
  disabled.
</p>
<p>
  While Ardour is chasing LTC, the main transport clock will display the 
  received Timecode as well as the delta between the incoming signal and 
  Ardour's transport position.
</p>
<p>
  A global offset between incoming timecode and Ardour's transport can be 
  configured in <kbd class="menu">Session &gt; Properties</kbd>.
</p>
<p>
  The user-bits in the received LTC frame are ignored.
</p>

<h3>MTC&mdash;MIDI Timecode</h3>
<p>
  Ardour's MTC slave parses <dfn>full timecode messages</dfn> as well as 
  MTC <dfn>quarter-frame messages</dfn> arriving on the 
  <code>ardour:MTC in</code> port. The transport will only start rolling 
  once a complete sequence of 8 quarter frames has been received.
</p>
<p>
  Ardour supports vari-speed and backwards playback but will only follow 
  MTC speed changes if the <kbd class="optoff">sync locked</kbd> option 
  is disabled.
</p>
<p>
  When Ardour is chasing MTC, the main transport clock will display the 
  received Timecode as well as the delta between the incoming signal and 
  Ardour's transport position.
</p>

<h3>JACK Transport</h3>
<p>
  When slaved to jack, Ardour's transport will be identical to 
  JACK-transport. As opposed to other slaves, Ardour can be used to control 
  the JACK transport states (stopped/rolling). No port connections need to 
  be made for jack-transport to work.
</p>
<p>
  JACK-transport does not support vari-speed, nor offsets. Ardour does not 
  chase the timecode but is always in perfect sample-sync with it.
</p>
<p>
  JACK-transport also includes temp-based-time information in Bar:Beats:Ticks 
  and beats-per-minute. However, only one JACK application can provide this 
  information at a given time. The checkbox 
  <kbd class="option">Session &gt; Properties &gt; JACK Time Master</kbd>
  configures Ardour to act as translator from timecode to BBT information.
</p>