View source for Multimedia Files

The FreeSpace 2 Open engine is able to use several different '''multimedia file formats''' for audio, animation and video playback. Retail FreeSpace 2 used the [[Wikipedia:Wav|WAV]] and '''ANI''' file formats, but the currently the FreeSpace 2 Open supports several [[Wikipedia:Ogg|Ogg]] container files as well. Support for the [[Wikipedia:Mp3|MP3]] file format was removed in favor of Ogg. The game engine also supports the custom '''.EFF''' animation format, as well as [[Wikipedia:APNG|APNG]] (as of commit 76ffc2668 / 3.8.0).

==Ogg==
'''Ogg''' is a file format for compressed multimedia files.  Unlike MP3, Ogg is an open-source, open-standard container format with a permissive license, both of which allow it to be incorporated into the FS2_Open source code.  Also unlike MP3, Ogg is a [[Wikipedia:Container_format|container format]], meaning that it can contain video data (via the [[Wikipedia:Theora|Theora codec ]]) in addition to audio data (via the [[Wikipedia:Vorbis|Vorbis codec]]).

Since Ogg delivers significantly smaller file sizes than [[Wikipedia:Wav|WAV]], while retaining substantially the same level of audio quality, it is becoming more and more frequently used in FSO-targeted mods.  Ogg Vorbis is not, however, a lossless format -- i.e., it is not possible to exactly reconstruct the original data from an Ogg Vorbis file because some is "lost" in the conversion process.  This is not usually a problem, however, because a high-quality Ogg Vorbis file is usually indistinguishable from the source.  The lossless counterpart to Ogg Vorbis is [[Wikipedia:Free_Lossless_Audio_Codec|FLAC]], which can be contained in Ogg also.

Vorbis uses a quality parameter between -1 and 10 as a measure of quality. 5 is the default, giving around 160kbps. The higher the number, the higher the quality, but anything over 5 is probably pointless.

Audacity and Goldwave are two popular programs that allow WAV files to be converted to Ogg Vorbis audio.  Audacity is Free Software, while Goldwave is shareware that ceases to function after a period of time.

Please note that this is a fso feature and is not supported by the original retail FreeSpace 2.

==WAV==
The most common sound file format. WAVs are uncompressed and take up a larger amount of space than almost any other sound file type, so consider converting them to the [[*.OGG|Ogg]] Vorbis format (supported only by SCP) before including them in your campaign. Audacity and Goldwave are two examples of programs that can make this conversion. [http://www.rarewares.org/ogg-oggdropxpd.php oggdropXPd] is an useful drag-and-drop encoder.

==ANI==  
FreeSpace uses the ANI format for animation effects. It can be used either for an effect (explosions, etc.), an interface animation, or as a ship texture.

===Creating an ANI file===

Using [http://www.descent-network.com/cgi-bin/descman.cgi?module=anibuilder AniBuilder], one can create new ANI files from AVI movies or rendered frames.

To create your own ANI:

#Create your scene in a 3D animation program or in FreeSpace. You can capture game footage using free recording software such as [http://www.planetgamecam.com GameCam], a preexisting movie, or you can render your own. Volition used the expensive [[Wikipedia:3ds_Max|3ds Max]] for their animations, but the free [[Wikipedia:Blender_(software)|Blender]] is just as good, and there are plenty of tutorials available for both. Alternately, ANIs can simply have one or two static frames.
#Output your movie to individual 24- or 32-bit BMP frames, numbered in sequence (starting with aniname0000.) You can check your desired resolution by looking at the type of ANI you want to replace, with the exception of up to 660x300 acceptable for high-resolution command briefing animations in FreeSpace Open. If you have a movie, use a program such as [[Wikipedia:Virtual_Dub|Virtual DUB]] to convert the AVI into a series of BMP files and crop or resize them as necessary.
#Convert your BMP frames to PCX files with a common palette. Certain interface art (for example, briefing icons and HUD head animations) requires an exact palette, which you can import from an existing ANI using a paint program such as [[Wikipedia:GIMP|GIMP]]. But in most cases, you will want to convert them to an optimized common palette. Best results are achieved with [http://freespacemods.net/download.php?view.520 BRIGHT]. AniBuilder can attempt to do this by itself but the results are almost always very poor.
#Use AniBuilder to convert the PCX files to an ANI. Some animations, such as ship/weapon loadouts and main hall animations, require keyframes; refer to the existing animations for how to insert these.

A more technical definition of ani files can be found [[ANI_Formal_Definition|here]].

==EFF==
FreeSpace 2 uses the EFF ASCII format text files to store information about animated effects. These animated effects can be used for various effects such as in game animations and animated textures. Please note that this is a fso feature and is not supported by the original retail FreeSpace 2.

===Creation of EFF animation===
*For EFF animation all the individual frames of the animation have to be present in one of the [[Graphic Files|graphic file formats]] supported by the game engine.
*All files related to the EFF animation have to named so that the name of actual .EFF animation forms the basic structure of the filename. 
**'''Graphic files''' add the 4 digit number - that identifies the frame where the file is used - after the animation name, starting from 0 (example_0000.dds, example_0001.dds etc.)
**'''ASCII file''' contains the information of the animation (example.eff)

===Contents of a EFF file===

====$Type:====
*Defines the file format of the graphics file used for the EFF animation
*Syntax: '''''String''''', for example ''DDS''

====$Frames:====
*Defines the length of the number of the frames in the animation
*Syntax; '''''Integer'''''

====$FPS:====
*Used ''optionally'' to define the '''frames per second''' value for the animation
*Syntax: '''''Integer'''''

====$Keyframe:====
*Used ''optionally'' to define a keyframe for EFF used as part of the interface.
*Syntax: '''''Integer''''' (The frame number, starting at index 0. Do not specify numbers greater than the number of frames)

====Example====

Let's say you have three dds (TGA and pcx are also acceptable) files (named 1_0000, 1_0001, and 1_0002) you want to make into an animation, but you don't want to use anibuild and therefore compromise quality.

Your EFF file would be like this:

Filename (the filename, not information to be entered. This must match up with characters before _xxxx in frames): 1.eff

 $Type: DDS
 $Frames: 3
 $FPS: 5

This EFF effect file would display one frame after another at 5 frames a second, skipping back to the beginning at the end. 

'''Please note''' that in FSO 3.6.10 and earlier, EFF cannot be used for streaming files (head animations, icons, mainhall, cbanis, ect.) and is meant ONLY for weapon/explosion effects and animated textures.

==APNG==

The places in FSO where APNGs make most sense are

* Command Brief Anims
* Intel Anims (techroom)
* Loading Screen Anim
* HUD Anims (e.g. headz, lock, etc)
* Mainhall animations

You CAN use APNGs for any other animation if you wish, e.g. animated glows, weapon impact effects, explosions, shield anims, etc. However, EFF with DDS would generally be a better choice because they're compressed in a format your video card can use directly, and thus they use much less video RAM.

Having said that, in many cases the apng files on disk (only) will be smaller than other animation formats which can mean reduced modpack sizes. e.g. the 2_intel_earth.png file is 7.5MB, compared with 15MB for the mediavps_2014 ANI file. Likewise an example EFF+PNG headani was 3.8MB as png frames, the APNG was 2.1MB. Note that this reduction heavily depends on the content of the APNG. From some rough tests done by Axem & niffiwan it seems that APNGs with a transparent background and an object moving through the background will probably fair poorly. One such example only reduced from 11MB to 9.9MB. This is because the best APNG compression method is diff/delta frames composed over the previous frame, and it can't draw a transparent pixel over the top of a non-transparent one. Therefore with a transparent background the frame needs to get completely redrawn, making the filesize larger.

Lastly, FSO uses the .png extension for apngs, not .apng (see [https://github.com/scp-fs2open/fs2open.github.com/pull/537#discussion_r53765499 here] for more info on why if you're curious)

====Simple APNG creation====

Here's steps on how to create simple APNGs.

1) Create your animation in your favourite animation application and save it as a PNG file stream. It'll be easiest if the frames are named in ascending order; e.g. anim_0000.png, anim_0001.png, etc (not strictly needed, just easier). Remember you have 24 bit colour & 8 bit alpha available, there's no need for a custom palette or special transparency colours.

2) Get an apng assembler. There's a bunch available on the internet, online only versions, local installs, command line and GUI. I've personally used the apngasm command line version so that's what I'll use in my example.

* [https://github.com/apngasm/apngasm/archive/3.1.6.zip Latest apngasm source (3.1.6)]
* [https://github.com/apngasm/apngasm/releases/download/3.1.3/apngasm_3.1-3_AMD64.exe Latest Windows 64bit executable (3.1.3)]
* For OSX they say use homebrew; I have no idea how to do this, sorry!

Note that the [http://www.reto-hoehener.ch/japng/ Japng Editor] allows you to open up apngs and see exactly what each frame is doing, e.g. when the assembler has chosen to use delta frames vs complete frames, etc.

3) Use the assembler to create your apng

You need to know what frame delay you want between all frames... and that's it for a simple animation.

Here's an example using frames exported from the mediavps_2014 intelligence ANI file for "Earth" (I used aniview32 to export the frames to BMPs, then imagemagick to convert them to 24bit PNGs). The FPS for the ani is 15.

<pre>
apngasm -d 67 -o 2_intel_earth.png 2_intel_earth_0*.png

-d specifies the default frame delay for each frame (67 msec in the example)
-o specifies the output name, for FSO we'll use the .png extension
The last set of arguments is all the frames in animation order
</pre>

4) Configure the apng within FSO

In my example, copy 2_intel_earth.png to FSO/mod/data/intelanims

And that's it! 

====Advanced APNG creation====

There are some more advanced options for creating apngs which may be of use in certain circumstances.

1) Per Frame Delays

You can give each frame in the animation it's own delay, different to every other frame in the animation. To do this, just put the individual frame delay after the frames source image.

i.e.
<pre>
apngasm -d 67 -s -o 2_intel_earth.png 2_intel_earth_renamed_0000.png 500 2_intel_earth_0*.png
</pre>

This makes the 1st frame play for 500 ms, and all the other frames have a 67ms delay.

Note that the most recent versions of apngasm will do this for you if you include duplicated frames in your sequence. i.e. if you have 50 frames and two sequential frames are the same, then apngasm will create an apng with 49 frames, where one frame has double the frame delay of the rest.

2) Loading APNGs as PNGs

FSO will happily load an apng as a static image if you load it as an image rather than an animation. This is a bit hard to control for stuff internal to FSO, but you've got full control over this in LUA. Anyway, this could save you putting extra files in your mod, by default the 1st frame of the animation will be loaded as the static image. Or you can put any frame you like as the "1st frame" and tell apngasm to skip than frame when playing back as an animation.     

i.e.
<pre>
apngasm -d 67 -s -o 2_intel_earth.png special_1st_frame.png 2_intel_earth_0*.png

-s is the option to skip the 1st frame
special_1st_frame.png is the 1st argument without a preceding option and thus is the 1st frame processed by apngasm
</pre>

Maybe this could be of use if you wanted to (e.g.) have a selectable pilot image that's also the 1st frame in that pilots head ani (I dunno, I'm not sure if there's any real use cases for this or not, but as long as everyone knows about the option then people could think up tricky uses for it).

3) Looping

APNG's can set the number of times that they will loop. However, FSO ignores this in favour of the code controlling how any given animation will loop (e.g. cbanims always loop, headanis never loop, etc). So don't worry about the loop value as FSO will ignore it.

==Movie files==
{{Table38|
In the 3.8.0 release of FreeSpace Open a new cutscene system was added which uses [https://www.ffmpeg.org/ FFmpeg] for decoding video files. This added support for multiple video codecs and container formats. The following video codecs have been tested and are known to work:
* Theora (in Ogg container files)
* H.264 (in MP4 container files)
* VP8/VP9 (typically in WebM files)

The movie player always selects the "best" video channel and the corresponding audio channel which may cause problems if a movie file contains multiple video or audio streams. To make the behavior predictable a movie file should only contain one video stream and one audio stream.
}}

===Subtitles===
{{Table382|
For localization purposes the movie player also supports language specific subtitles encoded in the movie file. This code has not been tested with a lot of movie files so if you encounter issues with this part of the cutscene player please post the movie file in the forums so that the SCP can improve the cutscene player.
}}

[[Category:File Types]]