# The &aktion; Handbook

Chris
D.
Corbettis

    chris@corbettis.fsnet.co.uk

Guillermo
P.
Marotte

    g-marotte@usa.net

Developer
Lauri
Watts

    lauri@kde.org

Reviewer
2000
Chris D. Corbettis
&FDLNotice;
2002-02-04
1.99.00

&aktion; is a video player

KDE
aKtion
kdemultimedia
mpeg
avi
QuickTime
gif
xanim

## Introduction

&aktion; is a video player front end for Xanim. It supports numerous video codecs found on the Internet, including mpeg1, QuickTime and animated gif. Please report any problems or feature requests to the &kde; mailing lists.

## Using &aktion;

Here's a screenshot of &aktion;
Screenshot

Basic use of &aktion; is very simple. Right click in the main window or select the open icon in the toolbar, choose the movie you wish to watch, and press the OK button.

### The Context Menu

The Context menu is accessed by clicking the right mouse button over the playback window. It is used to quickly change the playback size, open video files and access the video file information dialog.

The Context menu is described further in .

### Full Screen &aktion;

It is possible to watch video playback in full-screen. Right click anywhere in &aktion; and choose Full screen. To exit, left or right click on the screen. You may need to enable this feature if it does not currently work.

If possible, use the XFree86 VidMode and DGA extensions. These extensions allow the application to automatically change the screen resolution to better fit the size of the video. Traditionally a video of, say, 320x200 would be scaled up on a 800x600 display. This scaling requires extra work and the result is not appealing at all. In the setup dialog there are two check boxes of interest:

Use XFree86-VidModeExtensions (if available)

  enable full screen mode

Grab the mouse

  &aktion; takes control of the mouse in full screen mode

## Command Reference

### The Video Context Menu

The Video Context Menu can be reached by right clicking inside the video window while a movie is loaded.

Video Information

  Displays a popup with information about the currently loaded movie, including the number of frames, the type of encoding, and its original pixel size.

Open File

  Opens a standard &kde; open file dialog box, with predefined filters for the file formats supported by &aktion;.

Setup

  Opens the Setup dialog, where you can configure &aktion;'s behavior.

Original Size

  Resizes the &aktion; window to the original size of the movie. This obviously has no effect unless you've already resized the movie at some point.

Half Size

  Resizes the &aktion; window to half the original size of the movie.

Double Size

  Resizes the &aktion; window to double the original size of the movie.

Maximized

  Resizes the &aktion; window to the maximum size possible to fit on your screen. The movie will maintain its own aspect ratio (that is, the relationship between its height and width) rather than distorting to fit your screen. A tall thin movie will still be a tall thin movie, but now maximized so that the largest dimension matches your screens largest dimension, with the exception of permanent screen features such as the &kicker; panel.

Full Screen

  Lets &aktion; take over your screen.

  Much more information is available in

### The Toolbar

The &aktion; toolbar
Toolbars

The toolbar is displayed along the bottom edge of the &aktion; window. It contains icons as follows:

Open

  Opens a standard &kde; open file dialog box, with predefined filters for the file formats supported by &aktion;.

Play

  Start playing the movie.

Stop

  Stop playing the movie.

Rewind

  Rewind the movie.

Fast Forward

  Fast Forward the movie.

Setup

  Opens the Setup dialog.

Help

  Opens the &aktion; help page (this document).

Just above the toolbar, on the right of the &aktion; window, is a volume slider. This can be used to adjust the volume of the movie, from lower (to the left) to higher (to the right).

### The &aktion; Setup dialog

The Setup dialog contains five main tabs:

- Audio

- Color

- Scaling

- Capture

- Others

The dialog also contains standard OK and Cancel buttons. Click OK to close the dialog and save all your changes, and click Cancel to close the dialog and discard all your changes.

#### Setup Audio

This tab contains options relating to audio during movies.

Audio enable

  Enables audio. If this is unchecked, there will be no sound during movies.

Skip frames for audio sync

  Checking this allows &aktion; to skip over occasional video frames, in order to keep the video and audio synchronised. Enable this if you have a slower machine and find that the video and audio are running at different speeds - often the audio track will finish while the video track is only part way through. There will be a loss of video quality if this is selected, but it will range from imperceptible to almost unwatchable, based mostly on the speed of your machine and how much memory it has.

Show volume slider

  Enable or disable display of the volume slider, above and to the right of the toolbar. This is enabled by default.

Initial volume (0-100)

  Sets the volume at the start of a movie. Changes made on the volume slider will be relative to this level. You may use the spinners to change the value, or type directly in the box.

#### Setup Color

This tab provides options to configure &aktion;'s use of color during movies.

Color mapping (non TrueColor displays)

  This section applies only to displays of less than TrueColor (16 bit) If you have problems with colors appearing strangely, try these options.

  TrueColor to 322 (static color)

    If selected, &aktion; will convert movies to the Static322 color map before displaying them.

  Color lookup table

    If this item is selected, &aktion; will create a palette to use as a lookup table. You can select how many frames to look ahead to create the table, but the higher the number you select, the more intense the memory use will be. The default is 5

  TrueColor to grayscale

    &aktion; will convert the movie to grayscale if this item is selected.

  None

    The default is None - &aktion; will not perform any color mapping. You should only try the other options if you have trouble with colors during movie playback.

Gamma of display:

  Set gamma of display. Gamma values greater than 1.0 typically brighten the animation.

#### Setup Scaling

This tab contains items relating to the display size of the movie.

Display scale

  Sets the size of the movie, in relation to its original size

  You may choose from any of the following values

  - Original size
  - Half size
  - Double size
  - Maximised
  - Full Screen
Full screen

  Further options relating to using &aktion; in full screen mode.

  Use XFree86-VidModeExtensions (if available)

    Enables full screen mode. Explained further in the section on Using &aktion; fullscreen

  Grab the mouse

    Takes control of the mouse while in full screen mode.

#### Setup Capture

&aktion; allows you to capture or take a snapshot of frames from the movie you are viewing, by simply pressing the key C. This tab contains options relating to this feature.

Output file format

  Choose what format your captures will be saved as. You may choose from the following:

  - bmp
  - jpeg
  - pbm
  - pgm
  - png
  - ppm
  - xbm
  - xpm

  The default is png

Output file directory:

  Choose where the screen captures will be saved. The default is `~` (your home directory.) You may type a path to a different directory directly in the text box, or you can press the ... to open a file selection dialog and browse to the desired location.

#### Setup Others

This tab contains other miscellaneous options.

Video Loading

  This section contains options relating to pre-loading of movies. You may choose one of the following:

  Preload animation into memory

    Loads the whole animation into your computers memory before it begins to play.

  Preload and uncompress animation

    Loads the whole animation into your computers memory, and uncompresses it, before beginning to play it.

  Read each sector only when needed

    Performs no preloading, reading each section of the movie from disk as it's needed.

  The default is Read each sector only when needed

Use X11 shared memory

  This is unavailable if you chose "Preload and uncompress animation" in the section above.It is deselected by default.

Use X11 multi buffering

  If selected, &aktion; will use X11 Buffering (if present) to smooth animations by double-buffering. It is selected by default.

Use Pixmap instead of Image in X11

  If selected, &aktion; will use Pixmap instead of Image in X11shared. This option has no effect if the animation is buffered.

Initial directory

  Set the directory that is shown when you choose to open a new movie. You may type a value directly in the text box, or use the ... button to browse to your preferred location. Of course, this is only the default directory, and you can browse to another location when actually opening movies. By default this is empty, which in most cases results in &aktion; beginning to look for movies from your home directory.

Loop animation

  If selected, when the movie reaches its end, it will begin over at the start, until you press the Stop button.

Automatically start playing video

  If this is chosen, &aktion; will begin playing the selected movie as soon as you have selected it. If this is not checked, you will have to press play yourself to start playing the movie.

Extra XAnim parameters

  If you wish to pass any extra parameters to the underlying XAnim application, you may enter them here.

## Developer's Guide to &aktion;

&aktion; includes the `KXAnim` widget wrapper, with it you can include video playback in your own programs.

KXAnim
KXAnim Class Reference

### KXAnimChildren

A xanim wrapper to allow video playing in your apps.
18/08/2000

    Public Members

          KXAnim (QWidget *parent, const char *name=0)
          ~KXAnim ()
          void setFile (QString file)
          void setAutoResize (bool val)
          bool getAutoResize ()
          void updateSize ()
          void setLoop (bool val)
          bool getLoop ()
          QString getVideoFileName ()
          int getVideoHeight ()
          int getVideoWidth ()
          float getVideoSpeed ()
          int getVideoFrames ()
          QString getVideoCodec ()
          QString getErrorCode ()
          QString getErrorString ()
          bool isPlaying ()
          bool isActive ()
          void resetXAnimDefaults ()
          void setAudio (bool val)
          void setAudioSync (bool val)
          void setInitialVolume (int val)
          enum colorMap { static332, lookupTable, grayScale, none }
          void setColorMapping (colorMap val)
          void setColorAhead (int val)
          void setGammaDisplay (float val)
          void setResizing (bool val)
          void setScaleFactor (float val)
          void setScaleHFactor (float val)
          void setScaleVFactor (float val)
          void setScaleWidth (int val)
          void setScaleHeight (int val)
          void setScaleDisplayToBuffer (bool val)
          void setScaleFactorB (float val)
          void setScaleHFactorB (float val)
          void setScaleVFactorB (float val)
          void setScaleWidthB (int val)
          void setScaleHeightB (int val)
          void setScaleBufferToDisplay (bool val)
          void setLoading (int val)
          void setX11Shared (bool val)
          void setMultiBuffer (bool val)
          void setUsePixmap (bool val)
          void setX11VisualClass ( const char *val)
          void setPauseAt (int val)
          void setExtraParameters (const char *val)
          void setExecutable (const char *val)

    Public Slots

          void play ()
          void pause ()
          void stop ()
          void stepForward ()
          void stepBack ()
          void stepForwardWA ()
          void stepBackWA ()
          void toggleSound ()
          void volumeIncrement ()
          void volumeDecrement ()
          void setVolume (int v)
          void faster ()
          void slower ()
          void resetSpeed ()

    Protected Members

          void changeProperty ( const char * c)
          virtual void closeEvent ( QCloseEvent *)
          virtual void mousePressEvent ( QMouseEvent *)

    Signals

          void stopped ()
          void mouseClick ( QMouseEvent *)

#### Detailed Description of `KXAnim`

#include <kxanim.h>

Inherits: `QWidget`

Widget class for video playing

This widget is an xanim wrapper to easily allow the video playing on your applications.

    KXAnim
    QWidget *parent
    const char *name=0

[public]

  Constructor. The parent argument is NOT optional.

    void setFile
    QString file

[public]

  Use this method to tell the player the name of the file to play. The file will not start to play until you call the `play()` slot. You need to call `stop()` before you can set a new filename.

  After calling this method, you should wait for an stopped signal. Just then, the information about the file will be available.

  Also check for KXAnim::getErrorNumber and `getErrorString` to know if there was some error.

    void setAutoResize
    bool
    val

[public]

  If `val`==true, the widget will resize by himself after the `setFile()` to fit to the size of the video. If `val`==false, the video size will be adjusted to fit to the widget size.

  The size of the widget is automatically updated by `setFile` and play But if you need to know the effective size of the widget *before* you call `play`, you need to call `updateSize` manually.

  Default is true

    bool getAutoResize

[public]

  Returns the auto-resize state (see `setAutoResize` ).

    void updateSize

[public]

  Updates the widget size to fit video size (taking care of the scale factors that applies). See `setAutoResize` .

    void setLoop
    bool val

[public]

  If `val`==true, the video will loop forever.

  Default is true

    bool getLoop

[public]

  Returns the loop state ( see `setLoop` ).

    QString getVideoFileName

[public]

  Returns the current video file name (or an empty string, if there's no video yet).

    int getVideoHeight

[public]

  Returns the video height (in pixels).

    int getVideoWidth

[public]

  Returns the video height (in pixels).

    float getVideoSpeed

[public]

  Returns the video playback speed (in frames per second).

    int getVideoFrames

[public]

  Returns the number of frames in the video.

    QString getVideoCodec

[public]

  Returns the string that describes the video codec.

    QString getErrorCode

[public]

  Returns the the error code number. You should check this number after a `setFile`. If the code is zero , the there were no errors. To get a string containing a description see `getErrorCode`.

    QString getErrorString

[public]

  Returns the string that describes the error during `setFile`.

    bool isPlaying

[public]

  Returns true is the video is in play mode. Otherwise it returns false.

    bool isActive

[public]

  Returns true is the video is active. Otherwise it returns false. The widget is NOT Active only when it's stopped. Therefore, you can use this method to check if the video is REALLY stopped.

    void resetXAnimDefaults

[public]

  This method reset all the configuration parameters to their default values.

    void setAudio
    bool val

[public]

  If `val`==true, enables sound output.

  Default is true

    void setAudioSync
    bool val

[public]

  If `val`==true, allows xanim skip video frames for audio sync.

  Default is true

    void setInitialVolume
    int val

[public]

  Sets the initial audio volume.

  Default is 40

enum colorMap ( static332, lookupTable, grayScale, none ) [public]

  See setColorMapping .

    void setColorMapping
    colorMap val

[public]

  Tells `KXAnim` which type of color mapping to use for non truecolor displays.

  If `val`==KXAnim::static322, xanim will convert truecolor anims to static322.

  If `val`==KXAnim::lookupTable, xanim will sample the color of truecolor animations ahead of time and forms a color lookup table.

  If `val`==KXAnim::grayScale, xanim will convert TrueColor animations to gray scale.

  Those three option are ignored for TrueColor and DirectColor displays.

  if `val`==KXAnim::none, xanim will use the default color mapping.

  Default is KXAnim::none

    void setColorAhead
    int val

[public]

  This sets the number of frames ahead to use for the look up table when using KXAnim::lookupTable in `setColorMapping`.

  Default is 5

    void setGammaDisplay
    float val

[public]

  Set gamma of display. Gamma's greater than 1.0 typically brighten the animation.

  Default is 1.0

    void setResizing
    bool val

[public]

  If `val`==true, the video size can be changed "on the fly".

  Default is true

    void setScaleFactor
    float val

[public]

  Scale the size of anim by "`val`" before displaying.

  Default is 1.0 (no scaling)

    void setScaleHFactor
    float val

[public]

  Scale the horizontal size of anim by "`val`" before displaying.

  Default is 1.0 (no scaling)

    void setScaleVFactor
    float val

[public]

  Scale the vertical size of anim by "`val`" before displaying.

  Default is 1.0 (no scaling)

    void setScaleWidth
    int val

[public]

  Scale the animation to have width "`val`" before displaying.

  Default is 0 (no scaling)

    void setScaleHeight
    int val

[public]

  Scale the animation to have height "`val`" before displaying.

  Default is 0 (no scaling)

    void setScaleDisplayToBuffer
    bool val

[public]

  Copy display scaling factors to buffering scaling factors.

  Default is false.

    void setScaleFactorB
    float val

[public]

  Scale the size of anim by "`val`" before buffering it.

  Default is 1.0 (no scaling)

    void setScaleHFactorB
    float val

[public]

  Scale the horizontal size of anim by "`val`" before buffering it.

  Default is 1.0 (no scaling)

    void setScaleVFactorB
    float val

[public]

  Scale the vertical size of anim by "`val`" before buffering it.

  Default is 1.0 (no scaling)

    void setScaleWidthB
    int val

[public]

  Scale the animation to have width "`val`" before buffering it.

  Default is 0 (no scaling)

    void setScaleHeightB
    int val

[public]

  Scale the animation to have height "`val`" before buffering it.

  Default is 0 (no scaling)

    void setScaleBufferToDisplay
    bool val

[public]

  Copy buffering scaling factors to display scaling factors.

  Default is false.

    void setLoading
    int val

[public]

  0: `KXAnim` will load the entire video into memory.

  1: `KXAnim` will load and decompress the animation entirely into memory before displaying.

  2: `KXAnim` will read each sector only when needed

  Default is 2.

    void setX11Shared
    bool val

[public]

  If `val`==true, `KXAnim` will use X11 shared memory (this is mutually exclusive with `setPreload` .

  Default is false.

    void setMultiBuffer
    bool val

[public]

  If `val`==true, `KXAnim` will use X11 Buffering (if present) to smooth animations by double-buffering.

  Default is true.

    void setUsePixmap
    bool val

[public]

  If `val`==true, `KXAnim` will use Pixmap instead of Image in X11shared. This option has no effect if the animation is buffered.

  Default is false.

    void setX11VisualClass
    const char *val

[public]

  Select the best X11 Visual of Class... when displaying the animation. `val` can be anyone of the following strings and is case insensitive:

  - default
  - staticgray
  - grayscale
  - staticcolor
  - pseudocolor
  - truecolor
  - directcolor

  Default is default.

    void setPauseAt
    int val

[public]

  This will pause XAnim at frame `val`. `val`=-1 disables this option.

  Default is -1 (no pause).

    void setExtraParameters
    const char *val

[public]

  Use this method to pass any extra parameters you want to xanim (separated by spaces).

    void setExecutable
    const char *val

[public]

  Use this method to set the executable name for xanim. Default is "xanim", but you can change it, for instance, if you don't have xanim in the path.

    void play

[public slot]

  Start playing the video.

    void pause

[public slot]

  Pauses the video playing (xanim is still runnig).

    void stop

[public slot]

  Stops the video and exit xanim (don't worry about it, it's transparent for the class user).

  Calling this slot doesn't mean that the video will stop immediately. Use the stopped signal to know exactly when the player is set to the inactive mode (see `isActive` ).

    void stepForward

[public slot]

  Single step forward one frame. Pauses the video playing.

    void stepBack

[public slot]

  Single step back one frame. Pauses the video playing.

    void stepForwardWA

[public slot]

  Single step forward one frame staying with anim. Pauses the video playing.

    void stepBackWA

[public slot]

  Single step back one frame staying with anim. Pauses the video playing.

    void toggleSound

[public slot]

  Toggle sound between ON/OFF.

    void volumeIncrement

[public slot]

  Increment volume by 1.

    void volumeDecrement

[public slot]

  Decrement volume by 1.

    void setVolume
    int v

[public slot]

  Setup volume where `v` is a number from 0 to 100.

    void faster

[public slot]

  Increase animation playback speed.

    void slower

[public slot]

  Decrease animation playback speed.

    void resetSpeed

[public slot]

  Reset animation playback speed to original values.

    void changeProperty
    const char * c

[protected]

  Don't use it! This is internally used for the communication with xanim.

    void stopped

[signal]

  This signal is emitted after a call to the `stop()` slot, and means that the player has really stopped playing (that xanim is inactive) (see `stop`).

    void mouseClick
    QMouseEvent *

[signal]

  This signal is emitted when the user clicks into the widget.

## Questions and Answers

What does the Unsupported video codec message mean?

It means the video format can not be played. This may be because you do not have a full featured xanim installed. See the next answer for more details.

There are some codecs that will not be playable for the foreseeable future. The one that may affect you the most is Sorenson as used in QuickTime 4.

How do I get the full featured xanim?

Go to the xanim home page and follow the instructions to install the cinepak, indeo and creative video codecs. You may need to recompile xanim, but check your distributions documentation as some are easier to install than others.

How do I know if the VidMode and DGA extensions are available on my system?

There are two ways to check. Which one you use depends on how you installed &aktion;.

Installed &aktion; from source

  Check the output of `./configure`, you should see `"checking for VidMode extensions..."`. If the script prints a `"no"` after this line, then you don't have the extensions.

Installed &aktion; binary (rpm or deb)

  Look in your system for two files called: `libXxf86vm.a` and `libXxf86dga.a`, if you have them, good.

In both cases, if you don't have the extensions, check that you've installed the XFree86-devel rpm package from your Linux box. The extensions are included in this package.

How do I know if the VidMode extensions are working on my system?

Try switching video modes with CTRL ALT numpad +. If nothing happens, you may only need to enable additional resolutions. See the next answer for more details.

How do I set up aditional video modes?

You should have a video configuration utility provided with your distribution. If not, there is always XF86Config available.

Enable as many resolution modes as you can. At the very least, you will want to enable 640x400 alongside your standard everyday resolution.

## Credits and License

&aktion;

Program copyright 2000 Guillermo P. Marotte g-marotte@usa.net

Contributors:

- Benjamin Sher sher07@bellsouth.net

Xanim author:

- Mark Podlipec

Documentation copyright 2000 Chris D. Corbettis chris@corbettis.fsnet.co.uk

&underFDL; &underGPL;

## Installation

### How to obtain &aktion;

&install.intro.documentation;

### Requirements

In order to successfully use &aktion;, you need &kde; 2 and xanim 2.70.7.0 or higher. Full screen mode requires VidMode and DGA extensions to be installed and working.

All required libraries as well as &aktion; itself can be found on The &aktion; home page and the Xanim home page

### Compilation and Installation

&install.compile.documentation;

### Configuration

Don't forget to install xanim before &aktion;.

&documentation.index;