doc/design/may_2017_review.tex

   1 \documentclass{article}
   2 \renewcommand{\c}[1]{\texttt{#1}}
   3 \begin{document}
   4
   5 \section{The butler}
   6
   7 Adding audio to the preview means that we have an audio thread which
   8 needs real-time access to audio data.  This means that we must have a
   9 separate decoding thread.
  10
  11 This is implemented by having a \c{Butler} class which runs a
  12 \c{Player}.  The \c{Butler} keeps ring buffers of video and
  13 audio data filled by its own thread.  It tries to keep the ring
  14 buffers full by calling \c{Player::pass()} when necessary.
  15
  16 The \c{Butler} fills its buffers and then waits for the
  17 \c{Butler::\_summon} condition to be raised, at which point it
  18 refills the buffers.
  19
  20 \section{Player}
  21
  22 \c{Player} has been returned to an API whereby the \c{Butler} calls
  23 \c{pass} and then signals are emitted by \c{Player} to give data to \c{Butler}.
  24
  25 Users should call \c{Player::pass} which will call \c{Video},
  26 \c{Audio} and \c{Subtitle} signals to be emitted.  These emissions
  27 will happen in no particular order but should be fairly
  28 closely-related in time (within \c{Butler::VIDEO\_READAHEAD} and
  29 \c{Butler::AUDIO\_READAHEAD} of each other, I think).
  30
  31 Users may also call \c{Player::seek}.  If \c{accurate} is set to true
  32 on this call, the following signal emissions will only be at or
  33 after the seek time.  If \c{accurate} is false the following
  34 emissions may be at any time after the seek time.
  35
  36 \c{Player} guarantees that emissions will represent continguous data.
  37
  38 \section{Decoders}
  39
  40 \c{Player} will request that \c{Decoder} classes seek as required.
  41 After seeks \c{Decoder}s can emit whatever data they like, and
  42 \c{Player} will discard them if they come before the time of an accurate
  43 seek.
  44
  45 \section{General remarks}
  46
  47 The \c{Player} class should feature very heavily in unit testing as it
  48 has significant influence.
  49
  50 \end{document}