<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY GFDL  SYSTEM "fdl-appendix.xml">
  <!ENTITY app "Cheese">
  <!ENTITY application "<application>&app;</application>">
  <!ENTITY appversion "2.22">
  <!ENTITY manrevision "2.22">
]>
<!--
      (Do not remove this comment block.)
  Template Maintained by the GNOME Documentation Project:
	  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Feb 12, 2002
-->

<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->

  <articleinfo>
    <title>&application; Manual</title>
    <abstract role="description">
      <para>
        &application; is a video and photo shoot program that for webcams
        (or other cameras) and can do some cool effects
      </para>
    </abstract>
    <copyright>
      <year>2007,2008</year>
      <holder>daniel g. siegel (dgsiegel@gmail.com)</holder>
      <holder>Jaap A. Haitsma (jaap@haitsma.org)</holder>
    </copyright>

  <!-- translators: uncomment this:

  <copyright>
   <year>2006</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

  -->

<!-- An address can be added to the publisher information.  If a role is
     not specified, the publisher/author is the same for all versions of the
     document.  -->
    <publisher role="maintainer">
      <publishername>Joshua Henderson (joshhendo@gmail.com)</publishername>
    </publisher>

   &legal;
   <!-- This file  contains link to license for the documentation (GNU FDL), and
        other legal stuff such as "NO WARRANTY" statement. Please do not change
        any of this. -->

    <authorgroup>
      <author>
        <firstname>Joshua</firstname>
        <surname>Henderson</surname>
	<email>joshhendo@gmail.com</email>
      </author>
      <author>
        <firstname>Jaap</firstname>
        <surname>Haitsma</surname>
	<email>jaap@haitsma.org</email>
      </author>

<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
       <othercredit role="translator">
        <firstname>Latin</firstname>
        <surname>Translator 1</surname>
        <affiliation>
          <orgname>Latin Translation Team</orgname>
          <address> <email>translator@gnome.org</email> </address>
        </affiliation>
        <contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>

    <revhistory>

      <revision>
        <revnumber>0.1</revnumber>
        <date>2007-12-04</date>
        <revdescription>
          <para role="author">Jaap A. Haitsma
            <email>jaap@haitsma.org</email>
          </para>
          <para role="publisher">Jaap A. Haitsma</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>0.2</revnumber>
        <date>2008-01-12</date>
        <revdescription>
          <para role="author">Jaap A. Haitsma
            <email>jaap@haitsma.org</email>
          </para>
          <para role="author">Joshua Henderson
            <email>joshhendo@gmail.com</email>
          </para>
          <para role="publisher">Jaap A. Haitsma</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>0.3</revnumber>
        <date>2008-08-20</date>
        <revdescription>
          <para role="author">Jaap A. Haitsma
            <email>jaap@haitsma.org</email>
          </para>
          <para role="author">Joshua Henderson
            <email>joshhendo@gmail.com</email>
          </para>
          <para role="publisher">Jaap A. Haitsma</para>
        </revdescription>
      </revision>

    </revhistory>

    <legalnotice>
      <title>Feedback</title>
      <para>
        To report a bug or make a suggestion regarding the &app; application or
        this manual, follow the directions in the 
        <ulink url="http://www.gnome.org/projects/cheese/"
	  type="http">&application; Contact Page</ulink>.
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo>

  <indexterm zone="index">
    <primary>&application;</primary>
  </indexterm>
  <indexterm zone="index">
    <primary>cheese</primary>
  </indexterm>

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
<section id="intro">
  <title>Introduction</title>
  <!-- manrevision 2.0 compatibility -->
  <anchor id="aboutex"/>
  <anchor id="notice"/>
  <indexterm>
    <primary>&application;</primary>
    <secondary>Manual</secondary>
    <tertiary>cheese</tertiary>
  </indexterm>

  <para>
  &app; is a video and photo shoot application with cool effects
  for the <systemitem>GNOME desktop</systemitem>
  </para>

</section>

<section id="using">
  <title>Usage</title>
  <para>
    The main screen of &app; looks like the screen shot below
  </para>

  <figure>
  <title>&app; screenshot</title>
    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="figures/cheese-screenshot.jpg" format="JPG"/>
        </imageobject>
      </mediaobject>
    </screenshot>
  </figure>

  <para>
    &app; defaults to photo mode, and needs to be changed to video mode if
    desired.
  </para>

  <section id="using-effects">
    <title>Effects</title>
    <para>
      To apply effects to the input of your webcam, click
      the button labelled <guibutton>Effects</guibutton>. When you go to the
      effects window, you will see a window similar to the image below
      <figure>
        <title>&app; effects screenshot</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/cheese-effects-screenshot.jpg" format="JPG"/>
            </imageobject>
          </mediaobject>
       </screenshot>
      </figure>

    </para>

    <para>
      You are able to select numerous effects to apply to your photo. To apply
      an effect, just click on the effect that you want. The button will appear highlighted.
      Selecting multiple effects will apply all the effects to
      your image (for example, if you apply <guibutton>Hulk</guibutton> and
      <guibutton>Vertical Flip</guibutton>, the
      input from the webcam will be altered to have a green shade and be up side down).
      To disable all effects, just click on the
      <guibutton>No Effect</guibutton> button.
    </para>
  </section>

  <section id="using-photomode">
    <title>Photo Mode</title>
    <para>
      Photo mode is the default mode that &app; opens in. When not in photo mode,
      click the button labelled <guibutton>Photo</guibutton>, press
      <keycombo><keycap>Alt</keycap><keycap>P</keycap></keycombo> or Menu:
      <menuchoice><guimenu>Cheese</guimenu><guimenuitem>Photo</guimenuitem></menuchoice>
      to change to photo mode.
      Photo mode will take a single photo every time the button labelled
      <guibutton>Take a photo</guibutton> or the <keycap>Spacebar</keycap>
      is pressed, and will save to disk.
    </para>
  </section>

  <section id="using-videomode">
    <title>Video Mode</title>
    <para>
      Video mode is a mode that allows you to take short videos using the webcam.
      When not in video mode, click the button labelled
      <guibutton>Video</guibutton>, press
      <keycombo><keycap>Alt</keycap><keycap>V</keycap></keycombo> or Menu:
      <menuchoice><guimenu>Cheese</guimenu><guimenuitem>Video</guimenuitem></menuchoice> to
      change to video mode. Video mode will start recording a video every time the
      the button labelled <guibutton>Start Recording</guibutton> or the
      <keycap>Spacebar</keycap> is pressed. The video will stop
      recording and save to disk when the button labelled <guibutton>Stop
      Recording</guibutton> or the <keycap>Spacebar</keycap> is pressed.
    </para>

    <para>
      The video mode does look any different to the screen shot of photo mode,
      except that the button labelled <guibutton>Take a photo</guibutton> will
      be either <guibutton>Start Recording</guibutton>
      or <guibutton>Stop Recording</guibutton>,
      and the button labelled <guibutton>Video</guibutton> is greyed out, whereas the button
      labelled <guibutton>Photo</guibutton> is not.
    </para>

    <note>
      <para>
        You can use both photo and video mode in Fullscreen. To do this, just click
        <menuchoice><guimenu>Cheese</guimenu><guimenuitem>Fullscreen</guimenuitem></menuchoice> to
        enter Fullscreen mode, or press <keycap>F11</keycap>. To exit Fullscreen
        mode, press <keycap>Esc</keycap> or <keycap>F11</keycap>.
      </para>
    </note>

  </section>
</section>

<section id="working-with">
  <title>Working with photos and videos</title>
  <section id="takingaphoto">
    <title>Taking a photo</title>
    <para>
      To take a photo in &app;, be sure to be in “Photo” mode. 
    </para>

    <para>
      To take a photo, apply the effects that you wish by clicking the button
      labelled <guibutton>Effects</guibutton>, click on the effects desired as
      described in a previous section and press the button labelled
      <guibutton>Back</guibutton>. You should now have the effects that
      you clicked on applied to the webcam input.
    </para>

    <para>
      To take the photo, press the button labelled <guibutton>Take a photo</guibutton>
      or press the <keycap>spacebar</keycap>. You will then
      see &application; count down from 3 or instantly take the photo, depending on your settings. When the photo is taken, your entire screen
      will flash white, and the photo that was just taken will appear in the photo
      stream at the bottom of the program window.
    </para>
  </section>

  <section id="recordingavideo">
    <title>Taking a video</title>
    <para>
      To take a video in &app;, make sure that the <guibutton>Video</guibutton>
      button has been pressed
    </para>

    <para>
      To start recording a video, press the button labelled <guibutton>Start
      Recording</guibutton> or press the <keycap>spacebar</keycap>.
      The time of how much video has been recorded will appear in the bottom right
      hand corner.
    </para>

    <note>
      <para>
        If your video appears to be jerky or have a low
        frame rate (only updating the picture every few seconds), it does not mean that the recording
        has a similar frame rate. In many cases, the recorded file will have a better frame rate.
      </para>
    </note>
  </section>
</section>

<section id="sharing">
  <title>Sharing Photos and Videos</title>
  <section id="view">
    <title>Viewing a photo or video</title>
    <para>
      To view a video or photo that has been taken, locate it in the photo stream and
      double click on it. Alternatively, you can right click on it and select <guimenuitem>Open</guimenuitem>.
      This will then open the file in the default application for that file type.
    </para>
  </section>

  <section id="saving">
    <title>Saving photos and videos to an alternate location</title>
    <para>
      To save a photo to an alternate place on your hard drive where you can easily
      find them, find the photo or video that you wish to save in the photo stream, right
      click on it and select <guimenuitem>Save As</guimenuitem> from the pop-up menu. This will bring up a
      standard <guilabel>Save File</guilabel> dialog that will allow you to rename the photo if desired
      and save to any location you wish.
    </para>
  </section>

  <section id="delete">
    <title>Deleting a photo</title>
    <para>
      To delete a photo from the photo stream, locate the photo you wish to delete in
      the photo stream, left click on it once and press the <keycap>delete</keycap> button on your
      keyboard. Alternatively, you can right click on it and click <guimenuitem>Delete</guimenuitem>.
    </para>

    <para>
      You will be prompted if you wish to delete it from the photo stream. To confirm,
      press the button labelled <guibutton>Move to Trash</guibutton>.
    </para>

    <note>
      <para>
        This will only move the image to the "trash", as well as remove from
        your photo stream. This will not remove the photo from your computer. To remove
        it from your trash, you will need to empty your trash.
      </para>
    </note>
  </section>

  <section id="email">
    <title>Send a photo by e-mail</title>
    <para>
      Photos can be directly emailed from &app;. You will need to have the default mail
      client set up with an email account, otherwise you will need to set one up. To email
      a photo, locate the photo you wish to email in the photo stream, right click on
      it and select <guimenuitem>Send by Mail</guimenuitem>.
    </para>

    <para>
      This will open the default mail client (for example, Evolution) and a new email
      message with the photo as an attachment.
    </para>
  </section>

  <section id="account-photo">
    <title>Set as Account Photo</title>
    <para>
      To set a photo as your account photo (which can be viewed from
      <menuchoice><guimenu>System</guimenu><guimenuitem>Preferences</guimenuitem>
      <guimenuitem>About Me</guimenuitem></menuchoice>, and which will also appear if the login window displays a list of
      user names with photos), locate the photo that you wish to set in &app;, right click
      on it and select <guimenuitem>Set as Account Photo</guimenuitem>
    </para>
  </section>

  <section id="fspot">
    <title>Export a photo to F-Spot</title>
    <para>
      To export a photo to F-Sport, locate the photo that you wish to export in your photo
      stream, right click on it and select <guimenuitem>Export to F-Spot</guimenuitem>. You will then be prompted from
      F-Spot if you wish to import the photos that are sent to it.
    </para>

    <note>
      <para>
        Depending on the version of &app; that you are currently using, F-Spot may prompt you
        to import the entire photo stream.
      </para>
    </note>
  </section>
</section>

<!--<section id="preferences">
  <title>Preferences</title>

  <para>
    Describe preferences over here
  </para>
</section>-->

<section id="faq">
  <title>Frequently Asked Questions</title>
  <!--<para>
    These are questions the mailing list gets asked frequently.
  </para>-->

  <section id="faq-sluggish">
    <title>The video is sluggish/has a slow response. What can I do?</title>
    <para>
      You may have set "<literal>ximagesink</literal>" (<guilabel>X Window System (No Xv)</guilabel>) as video-output.
      This means, that your cpu is doing all the work. Change it to "<literal>xvimagesink</literal>"
      (<guilabel>X Window System (X11/XShm/Xv)</guilabel>) in order to let your graphics card do the work.
    </para>

    <para>
      To change the settings, run <command>gstreamer-properties</command>,
      click the <guilabel>Video</guilabel> tab
      and change the appropriate settings.
    </para>
  </section>

  <section id="faq-mac">
    <title>I have a Mac with iSight and a ATI graphics card, and the colors are weird.</title>
    <para>
      This is a problem with the ATI graphics card, though there is a work around.
      Change the video-output to custom and insert the following: "<literal>ffmpegcolorspace !
      video/x-raw-yuv,format=(fourcc)YV12 ! ffmpegcolorspace ! xvimagesink</literal>".
    </para>

    <para>
      To change the settings, run <command>gstreamer-properties</command>,
      click the <guilabel>Video</guilabel> tab
      and select custom from the drop down menu.
    </para>
  </section>

  <section id="faq-work-gstreamer">
    <title>My webcam works with gstreamer, but does not work with &application;. What's wrong?</title>
    <para>
      Using <command>gstreamer-properties</command> mentioned in the above question, try changing from
      <guilabel>xvimagesink</guilabel> to <guilabel>ximagesink</guilabel> or vice-versa.
      If this still does not work run <command>cheese --verbose</command> on
      the command line and copy the logging into a bug report in our 
      <ulink url="http://bugzilla.gnome.org/browse.cgi?product=cheese" type="http">
      bug tracker</ulink>.
    </para>
  </section>

  <section id="faq-work-other">
    <title>My webcam works with other programs such as Ekiga, Camorama, but not with &application;. What's wrong?</title>
    <para>
      See if your webcam works when testing it in
      <command>gstreamer-properties</command>. If it works
      there, but not in &application;, please file a bug report in our 
      <ulink url="http://bugzilla.gnome.org/browse.cgi?product=cheese" type="http">
      bug tracker</ulink>.
    </para>
  </section>

  <section id="faq-store">
    <title>Where does &application; store my photos?</title>
    <para>
      Your photos are stored in ~/.gnome2/cheese/media. You can also save
      them to an alternate location from within &app;. Please see
      <xref linkend="saving"/> for
      information on this.
    </para>
  </section>

  <section id="faq-quickcam">
    <title>My Quickcam Express doesn't work with &application;...</title>
    <para>
      or gstreamer, and I see errors like "Not enough buffers. We got 1, we
      want at least 2" in the &application; output. With driver "qc-usb".
    </para>

    <para>
      Try running <command>qcset /dev/video0 compat=dblbuf</command> to enable double buffer
      compatibility mode, then restart &application;
    </para>
  </section>

  <section id="faq-no-camera-found">
    <title>"No Camera Found" Error Message</title>
    <para>
      "When I launch &app;, I get the message 'No Camera Found' but I have my webcam plugged into my computer".

      There are many situations this can happen in, and the exact problem that is causing this needs to be isolated.
      If possible, try each of the following to try and get your webcam working.
        1. Plug your webcam into another computer. If it works there, then it is a problem with
           with the connection to your computer, or the operating system if it was a different
           one on the other computer. Check the ports on your computer (try another one) and
           consult support personel for your particular operating system.
        2. See if your camera is being detected by your computer, on Linux, open up the terminal or console and type
           "dmesg" before you plug in your webcam. Notice the most recent entries, and then plug in your webcam. Type
           "dmesg" again and see if the most recent entries differ. If the message mentions a USB device being detected,
           and your webcam is the only USB device that has been changed, then your computer is detecting your webcam
           fine. If not, then test to see if the webcam is working on another computer. This may only work with USB
           webcams.
        3. As &app; uses the gstreamer backend, it is most likely because gstreamer is not detecting the webcam (or
           gstreamer has become corrupt). Please contact support personel for the particular operating system that
           you are running with as many details as possible. For Ubuntu, please use the <ulink url="http://ubuntuforums.org/" type="http">Ubuntu Forums</ulink>.
    </para>
  </section>

  <section id="faq-supported-webcams">
    <title>Which cameras are supported</title>
    <para>
      &app; uses gstreamer for video grabbing. So in principle &app; supports 
      any camera that works with GStreamer. In principle that should be any camera
      which support video4linux or video4linux2.
    </para>
  </section>
</section>

<section id="about">
  <title>About</title>
  <para>
    &app; was initially written by daniel g. siegel <email>dgsiegel@gmail.com</email>.
    as a Google Summer of Code project. Later Jaap A. Haitsma <email>jaap@haitsma.org</email> and also 
    others joined daniel in improving &app;.
    To find more information about &app;, please visit the
    <ulink url="http://www.gnome.org/projects/cheese" type="http">
    &application; web page</ulink>.
  </para>
  <para>
    To report a bug or make a suggestion regarding this application you can file
    a bug in our 
    <ulink url="http://bugzilla.gnome.org/browse.cgi?product=cheese" type="http">
    bug tracker</ulink>.
  </para>
  <para>This program is distributed 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. A copy of this license can be found at the
    <ulink url="http://www.gnu.org/licenses/gpl.html" type="http">GNU site</ulink>, or in the file
    COPYING included with the source code of this program.
  </para>
</section>

</article>
