Kinetophone FAQ
Version 0.2.0 (February 27, 2012)

Q1. Can I edit the Kinetophone narrator session file to filter
    unwanted segments?

A1. Yes, the session file is in XML format.  Using a text editor you
    can remove entries under the <segments> tag such as:

      <segment>
        <index>1</index>
        <start_frame>14435328</start_frame>
        <end_frame>31756799</end_frame>
        <ordinality>1</ordinality>
        <retake>0</retake>
      </segment>

    Make sure you remove the entry completely from the <segment> start
    tag to the </segment> end tag including the tags themselves.
    Leave at least one segment in the file.  Of course, it makes sense
    to make a copy of the session file and make changes to it rather
    than to the original.  You can also use XML style comment
    delimiters (<!-- to start, --> to end) to comment out segments or
    document your session file.

----

Q2. Why does video editor/viewer XYZ not correctly display the movies
    output from Kinetophone builder?  Are the movies corrupted?

A2. The movies output from Kinetophone builder are probably not
    corrupted.  By default, Kinetophone builder uses run length
    encoding (RLE) for video with the first video frame for each
    segment (source image) being a key frame/I-frame and the remainder
    being non-key frames/P-frames.  This is done to provide good
    compression.  Some video editors/viewers seem to need periodic
    key frames to synchronize image changes in the movie and even to
    encode the footage.

    One solution is to transcode the footage to a different video
    codec which is more compatible using ffmpeg or another suitable
    tool.  The RLE video encoding used by Kinetophone builder is
    lossless, so one conversion should not impact quality
    significantly, especially if the conversion is to a final format.

    Since the program uses the ffmpeg libraries for generating movies,
    ffmpeg is a good program to try first when converting the
    movies from Kinetophone builder.

    Another solution is to add more key frames to the movie.
    Kinetophone builder's -K <N> or --keyframe-period <N> command line
    option will output a full I-frame every <N> frames in the segment.
    Unfortunately, this creates HUGE movies and might cause further
    incompatibilities with video editing/viewing programs.  Other
    tools may also allow you to add key frames.

    A third method is using the multiple movie option (-u or
    --multiple-movies) to create separate movies for each segment.
    Some tools pick up on the transition to a new clip without having
    to add key frames.

    *** We would welcome feedback from users on this topic, since we want
    Kinetophone to be as flexible and useful as possible.

----

Q3. Why was the particular video codec/audio codec scheme chosen for
    output from Kinetophone builder?  Could you add support for codec
    XYZ?

A3. We wanted movie output to be in a format suitable for further
    editing/processing without duplicating existing functionality when
    possible.  The output from Kinetophone builder can be considered
    an intermediate video format.

    *** Regarding adding additional support, we would welcome ideas
    from users.  We may add support for additional codecs, if there is
    a need.

    Container:

    Kinetophone builder uses the ffmpeg mov container because it
    supports the qtrle (run length encoding) video codec as well as
    various uncompressed audio formats.

    Video codec:

    We chose the ffmpeg qtrle codec for video encoding because it uses
    lossless run length coding (RLE) which is suitable for an
    intermediate video format.  Although RLE via the ffmpeg qtrle
    video codec does not offer optimal intra-image compression, it is
    lossless.  The overall movie compression is good, and the
    codec is also well supported by third-party tools.

    Audio codec:

    Kinetophone narrator can record in various uncompressed signed PCM
    formats (16 bit, floating point, etc.) as well as FLAC lossless
    compression.  Kinetophone builder outputs all audio as
    uncompressed samples, using the same format as the original
    recording.  However, it converts the endianness when necessary due
    to format limitations.

    Since the generated movie footage is intended to be in an
    intermediate format, the audio is left uncompressed for the sake
    of quality.  The original recording can be in FLAC format to
    reduce its size.  You can compress the audio track in your final
    video output using a third-party tool.

----

Q4. I changed the location of my sound recording or source images, how
    do I use my Kinetophone narrator session file to build a movie?

A4. Kinetophone builder offers two command line options to help here:

    Sound recordings:

    To specify a different sound file use the -f <file name> or
    --sound-file <file name> command line option to
    kinetophone_builder.  This can be useful if you convert your sound
    file to a sample rate or format different from the original.  If
    you don't specify an output sound file to Kinetophone narrator, it
    creates a temporary one.  This file will most likely be deleted
    when you restart your system, so it is a good idea to move it to
    more permanent location.  The --sound-file option to the builder
    allows you to specify the new location.

    Source images:

    If you move your projects, you can change the location of source
    images stored in the session file by using the -D or --image-directory
    command line options to kinetophone_builder.

    Note that it is also possible to edit the session file and change
    the appropriate fields to update the recording path or image
    directory, but using the command line options might be
    preferable.

----

Q5. Why does the console recorder quit the program after I stop
    recording?  Why does the narrator say that no further recording is
    possible after recording?  Why does the builder exit with the
    "File exists" error when moving temporary movies to their
    destination?

A5. The short answer is because you are not using the -o or
    --overwrite command line option.  By default, Kinetophone programs
    will not overwrite files--this requires the overwrite option.
    Note that it is not a good idea to put the overwrite=yes option in
    a .kinetophone configuration file because overwrite will then be
    the default across the Kinetophone system of programs.

----

Q6. Why would I use the command line option --frame-format original to
    kinetophone_builder?

A6. This option creates movie footage with the maximum dimensions of
    all your source images.  It preserves the resolution of your
    original images.  If your video editor supports scaling of input
    movies, you can then create pan/scan effects in your video
    production.

----

Q7. I want to save my notes from Kinetophone narrator, how can I reuse them?

A7. You can save the notes to a session file at any time (whether or
    not you have a recording) by choosing File > Export > Session from
    the main menu.  When you restart the narrator, use the -n or
    --import-notes-from-file command line option to specify the
    session file with your notes.

----

Copyright 2012 Roan Trail, Inc.

This file is part of Kinetophone.

Kinetophone is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation, either version 2 of the License,
or (at your option) any later version.

Kinetophone is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.  You should have received
a copy of the GNU General Public License along with Kinetophone. If
not, see <http://www.gnu.org/licenses/>.
