From Aegisub Manual
Aegisub isn't a video (or media) player, but it still supports loading and working with video in various ways. This page is a reference of how Aegisub's loading and handling of video works; for a gentler introduction on how to just get things to display properly you may want to read the Typesetting Tutorial or Visual Typesetting pages.
To load a video file, go to the Video menu and press Open video file. What video files you can open depends on your video provider. To use a dummy (mockup, blank) video, press Use dummy video.
Supported formats: Windows
On Windows, your video provider is Avisynth by default, which in practice means Aegisub will try its best to load your video in the most reliable way possible. There are currently no less than six Avisynth functions it can try:
- Import() - Avisynth builtin function. Used to load Avisynth scripts, never used for anything else.
- AviSource() - Avisynth builtin function. Only works on AVI files, obviously. Requires a working Video for Windows (VfW) decoder to open the video. Tried first for .avi files, never for anything else. If it fails, Aegisub will try ffmpegSource() instead, if that fails try DSS2(), and if that too fails try DirectShowSource() (see below).
- MPEG2Source() - Only used to load .d2v files (DVD2AVI project files; otherwise known as indexed .VOB's ripped from DVD's). Tries to use neuron2's DGDecode to open the file; if Aegisub can't find or load that it'll try the old mpeg2dec3.dll instead; if that too fails, returns an error.
- ffmpegSource() - Tries to use Myrsloik's ffmpegsource plugin (comes with the default Aegisub install) to try to load the file; see its manual for information on what formats and codecs are supported and what problems they may suffer from. Tried first for anything that isn't .avs, .avi or .d2v. If Aegisub can't find it or it returns an error, falls back on DSS2() or if that isn't available, DirectShowSource(). Note that for VFR videos that are not in the Matroska (MKV) container, you will have to extract and load timecodes yourself or subtitle synchronization will be off! See the section about VFR below.
- DSS2() - Tries to find, load and use Haali's DirectShowSource2 plugin (comes with the Haali Media Splitter package and with the CCCP; the Avisynth plugin is avss.dll, you need to manually put it somewhere where Aegisub or Avisynth can find it, see below). That will in turn try to use your computer's DirectShow environment to open the file. Theoretically any file renderable by DirectShow should be supported, but since you are at the mercy of third-party splitters and decoders, your mileage may vary. As a rule of thumb, if it's playable in Windows Media Player, Aegisub should be able to load it. Do note that DSS2 converts variable framerate files to constant. Usually this is what you want and expect but if you're doing proper VFR subtitles, it isn't.
- DirectShowSource() - Uses DirectShowSource() (which ships with Avisynth) to try to load the file. Basically the same as DSS2, with the exception that it doesn't convert VFR to CFR. Warning: DSS is known to have problems with frame-accurate seeking. Do not use it if you can avoid it.
Aegisub will look for Avisynth plugins in its ?data directory (generally the folder where Aegisub.exe is, on Windows). You can also put them directly in your Avisynth plugins folder to get them autoloaded.
Anyway, what does all this mean to you as the average user? It means Aegisub can in theory open ANY video format as long as you are capable of playing it in Windows Media Player (or render it in GraphEdit), plus some that aren't playable there (such as .d2v's). At least it'll try its best to load it. You may however run into trouble with some of the more unusual formats and just because you CAN load something it doesn't mean it's a good idea to use it. Formats more or less guaranteed to work in a stable fashion with the default install include but is not limited to:
- XviD/DivX/other MPEG4 ASP codecs in AVI
- Most stuff stored in Matroska (except maybe some really oddball V_MS/VFW/FOURCC streams)
- Pretty much any standards-compliant MP4
If you change the video provider to dshow, Aegisub will try to interface directly with DirectShow to open the file. May help with some really oddball files, but is usually not recommended.
Supported formats: Unix
Under Unix or Unix-like systems (including but not limited to *BSD, GNU/Linux, and MacOS X) your video provider is ffmpeg, which means Aegisub will attempt to load the video using, well, ffmpeg, which should mean that anything supported by ffmpeg is supported; see its documentation for details. There are a few quirks however; for example libavformat is not used for Matroska (.mkv .mka .mks etc) files since its Matroska splitter has a lot of issues; instead Aegisub does its own parsing of such files (by using code borrowed from Haali's Matroska parser).
At the time of writing the ffmpeg interface isn't 100% stable (much like Aegisub in its entirety isn't 100% stable under Unix yet) but at least most AVI's, MKV's and MP4's seem to work in a decently reliable fashion.
Aegisub also supports providing a bogus video surface for you to render subtitles on without having any actual video loaded. The dummy video dialog box looks like this:
- The resolution of the dummy video in pixels. There are a few pre-defined choices in the dropdown menu; you can also specify the size yourself. Note that since the dummy video is RGB there are no particular restrictions with regards to odd widths/heights.
- The colour of the video surface. The color is solid by default; tick the box "checkerboard pattern" if you want some more variation.
- Frame rate
- Determines how long each frame is displayed by setting the number of frames per second (fps). Note that it is in fact possible to load VFR timecodes with dummy video.
- The duration of the video in frames. Below this number is shown the resulting duration in hours/minutes/seconds.
Aegisub does support playing back video, but it has been widely debated if it is a misfeature or not.
Before you press the "play" button
Think it through. Do you really want to play the video? (Hint: the answer is "no", you don't want to do that, at least not in Aegisub.) If you're trying to check if a subtitle matches up to something in the video, wouldn't it be easier to just step through the video frame-by-frame with the arrow keys? If you're proofwatching, wouldn't it be more convenient to do so in a real media player?
To conclude: in real world situations, you will never need to play the video from inside Aegisub. The mantra is: Aegisub isn't a media player; if you want a media player use a media player.
Video playing quirks
When you play video, Aegisub will try to play the audio along with the video, even if you haven't explicitly loaded it. This feature is currently somewhat unreliable, especially on non-Windows systems, so if you really want to play video and audio, pre-load the audio first (see working with audio).
Note that Aegisub does NOT guarantee audio/video synchronization. It does attempt it, but since the video rendering plus subtitle drawing is slower than in a real media player your computer may not be fast enough to keep up. Even if it is fast enough, you will probably still not get perfect synch. If you want that, use a media player.
A brief, highly simplified explanation of what a keyframe is, for the people who missed Video 101:
Modern video codecs compress video by storing as little information as possible. Instead of storing all frames in full (like a large amount of JPG pictures), they take occasionally take a keyframe, which is stored fully, and for each frame after that until the next keyframe, they only store what changed in the picture since the last frame. Hence, to seek to a given frame the decoder needs to find the previous keyframe and decode all frames between that frame and the sought one, which means seeking to keyframes is faster than to other frames. Keyframes are interesting mostly for scene timing reasons, because they usually appear at scenechanges. The first frame in a scene is almost invariably a keyframe, but beware - far from every keyframe is a scenechange! Most encoders insert a keyframe at least once every 250-300 frames, even if there hasn't been a scenechange.
Aegisub uses keyframe data at several places in the program. They are drawn as black lines on the video seek bar, and (by default) also displayed in the audio waveform/spectrum analyzer.
Loading and saving of keyframe data
Aegisub supports loading keyframe data directly from AVI and Matroska files, regardless of what video provider was used to open them. If you are using any video format other than AVI or MKV, you can still load keyframe data separately. Aegisub currently supports reading from two formats; its own keyframe file format (see specification below) and XviD first-pass .stat files. If you don't know what the latter is, ask your local encoding guru.
Aegisub can also write the currently loaded keyframe data to a keyframes file, which can be useful to avoid passing video files around in certain situations (audio timing for example).
Keyframe file specification
A keyframes file is a plain ASCII-encoded text file; both \n and \r\n is understood to mean a linebreak. Syntax example:
# keyframe format v1 fps 23.976000 0 30 70 82 130 131
The first line is the format specification; the string "# keyframe format v1". The next line consists of the lower-case string "fps " followed by the the FPS of the video file the keyframe data was generated from as a double-precision floating point number (".", 0x2E, full stop, is used as decimal separator regardless of system locale). Finally, after the fps line follows an arbitrary number of long integers (one per line), each representing the frame number of a keyframe. The frame numbers are zero-indexed; i.e. the first frame of the video is frame number 0.
Variable framerate video
Aegisub supports loading and working with variable framerate video. The how's and why's of VFR is far outside the scope of this manual (see for example the VFR thread on AnimeSuki or the Avisynth manual page for more information about VFR), but we will cover what you need to know about how Aegisub handles it.
Loading of Matroska timecode files (v1 and v2) is supported and useful if you have a VFRaC (Variable FrameRate assumed Constant; for example the frames of an VFR MKV stored in an AVI at a constant FPS, see the VFR thread linked above for details) video file but want the subs to sync to it. If you load a Matroska file, Aegisub will automatically read the timecodes from it directly. Do however note that this is NOT supported for any other potentially VFR formats like MP4 or WMV; for those formats you MUST demux and load timecodes yourself or the audio/video/subtitle synchronization will be wrong. Be aware that WMV in particular is frequently VFR even if you do not expect it.
VFR and hardsubbing
As long as you're not encoding with GDSMux, the encoding environment your subtitling filter is working in (i.e. Avisynth, VirtualDub or mencoder) will assume that the world is CFR, and hence the input file is VFRaC. This is obviously a problem since it messes up subtitle synchronization. Aegisub provides a way around this through the Framerate Transformation export filter, which takes the framerate of the VFRaC input file and the timecodes, and then changes every time code and override tag in the script so it can be hardsubbed on the VFRaC video and still sync up perfectly after timecodes are applied. To prepare a script for hardsubbing, make sure you have the timecodes loaded, then go to the File menu and press Export. Untick everything except the Transform Framerate filter. Choose the Variable output mode. It needs to know the FPS of the video you're going to hardsub the subtitles on; if you have video loaded Aegisub will assume that's it and insert it in the box for you. Note: if you have a Matroska or other VFR file loaded, remember that the FPS value Aegisub reports might not be the same as the one of the video you are going to hardsub the subtitles on.
OR: How to get your subtitles to not look stretched
The following paragraphs assumes that you have a working knowledge of what anamorphic video is and how aspect ratios work. If you feel unsure, you may want to consult a gentle but fairly complete introduction.
Image stretching and subtitle rendering
An anamorphic image needs to be stretched to the proper aspect ratio before it is presented to the viewer. On a computer, this is usually done by the video renderer, and thereby lies a problem. Most subtitle renderers (including VSFilter, the current "standard" renderer) do the subtitle drawing on the image before it is stretched, and since the renderer is not aware of any aspect ratio issues, the subtitles will be stretched along with the image when the video is displayed to the viewer, and therefore they will look stretched. Aegisub does its subtitle rendering this way as well (since that way it will be WYSIWYG with most players); you can test how it looks by using the "Override aspect ratio" in the video menu.
Compensating for the stretching
Fortunately it's easy to compensate for the stretching, since you know by how much the image will be stretched (since you know its original dimensions and the display aspect ratio). You just calculate how many percent the image will be stretched in either the X or the Y direction, and then set the ScaleX or ScaleY parameter in the style (or use the \fscx or \fscy overrides) to the same amount but in the other direction.
Example: we have a 704x480 image that we know will be displayed as 16:9 (or 1.7777...:1). If we assume that the player will stretch the width but leave the height untouched, this means that the new width will be:
(16 / 9) * 480 = 853.333...
which in percent is:
853.333... / 704 = 1.212121...
i.e. 121%. Hence, to compensate for this horizontal (X-direction) stretch we set ScaleY in all our styles to 121% to stretch the subtitles by the same amount, and after rendering they now no longer look stretched.
OR we can do the stretching in the other direction, assuming that the player changes the height of the image instead. Assuming the same image:
704 / (16 / 9) = 396
which corresponds to:
396 / 480 = 0.825
or 82.5%, which means we can compensate for the vertical (Y) compression by setting ScaleX to 82.5%.
Both of the above methods give the subtitles the proper aspect ratio, but depending on how the player does the stretching, you may get subtle variations in subtitle size. Aegisub (and indeed most video players and renderers) always changes the image width and never the height, except if you pick the "custom" aspect ratio and specify a resolution. Note that if you use the Matroska container, you may specify the display resolution directly, but player support of this varies.
Note that some odd subtitle renderers (most notably Media Player Classic's builtin renderer) are actually a part of the video renderer and will do the subtitle rendering after anamorphic stretching, resulting in stretched subtitles and much annoyance. With MPlayer's libass renderer, you can actually specify whether subtitles should be drawn before or after stretching by using the -vf parameter to move the subtitle renderer in the filter chain.
For more information about anamorphic video and aspect ratios in general (a deeply obfuscated topic that appears simple at a glance) the following links may be of interest:
- A Quick Guide to Digital Video Resolution and Aspect Ratio Conversions - Absolutely essential reading for anyone who wants to really understand the topic, but unfortunately far more than everything most people ever wanted to know about it.
- Widescreen.org: Aspect Ratios - the history and reasons for some common aspect ratios
- Wikipedia: Aspect Ratio (image)
- Wikipedia: Anamorphic Widescreen
The video menu
The following options are available from the video menu:
- Open video
- Opens video. Note that if you try to open another video with video already loaded, the original video will be closed first.
- Close video
- Unloads the currently open video.
- Shows list of recently opened videos.
- Use dummy video
- Opens a dummy video (see above).
- Show video details
- Shows some information about the currently open video. Details shown are filename, frames per second (for VFR files the average FPS is displayed), resolution and aspect ratio, length and decoder. Decoder being what filter/method Aegisub used to open the file.
- Open timecodes file
- Loads a timecodes file and applies it to the video, changing the video/subtitle synchronization.
- Save timecodes file
- Saves the currently loaded timecodes as a new v2 timecodes file.
- Close timecodes file
- Unloads the currently loaded timecodes.
- Shows list of recently opened timecodes files.
- Open keyframes
- Loads keyframe data from the given file. If you already have keyframe data loaded, it will be replaced by the one read from the file.
- Save keyframes
- Saves the currently loaded keyframes data to a keyframes file.
- Close keyframes
- Unloads the currently loaded keyframe data, if any. Note that it is not possible to unload keyframe data that was directly loaded from the video file; if you want to get rid of that for some reason, load a keyframes file with only frame 0 being marked as a keyframe.
- Shows list of recently loaded keyframe files.
- Detach video
- Detaches the video display and related controls from the Aegisub main window and moves it into its own window. To reattach the video to the main window, close the detached window. This feature can be particularly useful on multi-monitor setups.
- Set zoom
- Sets the video zoom level.
- Override aspect ratio
- Stretches the video to the specified aspect ratio by modifying the video width. Useful for anamorphic video (see above).
- Show overscan mask
- Draws a blue "mask" over the image, indicating the edges of the action safe (dark blue) and title safe (light blue) areas. Useful if you plan on showing your subtitles on a TV without adjustable overscan correction. For more information, see the Wikipedia pages on overscan, safe areas and overscan amounts. Aegisub follows the BBC guidelines on how big the safe areas should be.
- Jump to
- Seeks the video to the given time or frame.
- Jump video to start
- Seeks the video to the start time of the currently active line.
- Jump video to end
- Seeks the video to the end time of the currently active line.