The aKtion Handbook

Chris D. Corbettis

<chris@corbettis.fsnet.co.uk>

Revision 1.99.00

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

aKtion is a video player

Chapter 1. Introduction

Introduction

Chapter 1. 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.

Prev	Home	Next
The aKtion Handbook	Up	Using aKtion

Chapter 2. Using aKtion

Using aKtion

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 the section called “The Video Context Menu”.

Full Screen aKtion

Using aKtion

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

Prev	Home	Next
Using aKtion	Up	Command Reference

Prev	Home	Next
Introduction	Up	Full Screen aKtion

Chapter 3. Command Reference

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 section called “Full Screen aKtion”

The Toolbar

Command Reference

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).

Prev	Home	Next
Command Reference	Up	The aKtion Setup dialog

The aKtion Setup dialog

Command Reference

The aKtion Setup dialog

The Setup dialog contains five main tabs:

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.

Prev	Home	Next
The Toolbar	Up	Developer's Guide to aKtion

Prev	Home	Next
Full Screen aKtion	Up	The Toolbar

Chapter 4. Developer's Guide to aKtion

Developer's Guide to aKtion

Chapter 4. Developer's Guide to aKtion

aKtion includes the KXAnim widget wrapper, with it you can include video playback in your own programs.

KXAnim

Developer's Guide to aKtion

Name

KXAnimChildren — A xanim wrapper to allow video playing in your apps.

Synopsis

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(*parent, *name=0); QWidget *parent; const char *name=0; [public]

Constructor. The parent argument is NOT optional.

void setFile(file); 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(val); 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(val); 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(val); bool val; [public]

If val==true, enables sound output.

Default is true

void setAudioSync(val); bool val; [public]

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

Default is true

void setInitialVolume(val); int val; [public]

Sets the initial audio volume.

Default is 40

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

See setColorMapping .

void setColorMapping(val); 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(val); 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(val); float val; [public]

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

Default is 1.0

void setResizing(val); bool val; [public]

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

Default is true

void setScaleFactor(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleHFactor(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleVFactor(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleWidth(val); int val; [public]

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

Default is 0 (no scaling)

void setScaleHeight(val); int val; [public]

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

Default is 0 (no scaling)

void setScaleDisplayToBuffer(val); bool val; [public]

Copy display scaling factors to buffering scaling factors.

Default is false.

void setScaleFactorB(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleHFactorB(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleVFactorB(val); float val; [public]

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

Default is 1.0 (no scaling)

void setScaleWidthB(val); int val; [public]

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

Default is 0 (no scaling)

void setScaleHeightB(val); int val; [public]

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

Default is 0 (no scaling)

void setScaleBufferToDisplay(val); bool val; [public]

Copy buffering scaling factors to display scaling factors.

Default is false.

void setLoading(val); 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(val); bool val; [public]

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

Default is false.

void setMultiBuffer(val); bool val; [public]

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

Default is true.

void setUsePixmap(val); 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(*val); 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(val); int val; [public]

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

Default is -1 (no pause).

void setExtraParameters(*val); const char *val; [public]

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

void setExecutable(*val); 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).

Note

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(v); 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.

Prev	Home	Next
Developer's Guide to aKtion	Up	Questions and Answers

Prev	Home	Next
The aKtion Setup dialog	Up	KXAnim

Chapter 5. Questions and Answers

Questions and Answers

5.1. What does the Unsupported video codec message mean?
5.2. How do I get the full featured xanim?
5.3. How do I know if the VidMode and DGA extensions are available on my system?
5.4. How do I know if the VidMode extensions are working on my system?
5.5. How do I set up aditional video modes?

5.1.	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.
5.2.	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.
5.3.	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.
5.4.	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.
5.5.	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.

Prev	Home	Next
KXAnim	Up	Credits and License

Chapter 6. Credits and License

Credits and License

Chapter 6. Credits and License

aKtion

Contributors:

Benjamin Sher <sher07@bellsouth.net>

Xanim author:

Mark Podlipec

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.

Prev	Home	Next
Questions and Answers	Up	Installation

Appendix A. Installation

Installation

How to obtain aKtion

aKtion is part of the KDE project http://www.kde.org/.

aKtion can be found in the kdemultimedia package on ftp://ftp.kde.org/pub/kde/, the main FTP site of the KDE project.

Requirements

Installation

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

Prev	Home	Next
Installation	Up	Compilation and Installation

Compilation and Installation

Installation

Compilation and Installation

In order to compile and install aKtion on your system, type the following in the base directory of the aKtion distribution:

% ./configure
% make
% make install

Since aKtion uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the KDE mailing lists.

Prev	Home	Next
Requirements	Up	Configuration

Configuration

Installation

Configuration

Don't forget to install xanim before aKtion.

Prev	Home
Compilation and Installation	Up

Prev	Home	Next
Credits and License	Up	Requirements

The aKtion Handbook

The aKtion Handbook

Chris D. Corbettis

Introduction

Chapter 1. Introduction

Using aKtion

Chapter 2. Using aKtion

The Context Menu

Full Screen aKtion

Full Screen aKtion

Command Reference

Chapter 3. Command Reference

The Video Context Menu

The Toolbar

The Toolbar

The aKtion Setup dialog

The aKtion Setup dialog

Setup Audio

Setup Color

Setup Scaling

Setup Capture

Setup Others

Developer's Guide to aKtion

Chapter 4. Developer's Guide to aKtion

KXAnim

Name

Synopsis

Detailed Description of KXAnim

Note

Questions and Answers

Chapter 5. Questions and Answers

Credits and License

Chapter 6. Credits and License

Installation

Appendix A. Installation

How to obtain aKtion

Requirements

Requirements

Compilation and Installation

Compilation and Installation

Configuration

Configuration

Detailed Description of `KXAnim`