FFmpeg/libavcodec/ass.h
Clément Bœsch 7c1a002c78 subtitles: introduce ASS codec id and use it.
Currently, we have a AV_CODEC_ID_SSA, which matches the way the ASS/SSA
markup is muxed in a standalone .ass/.ssa file. This means the AVPacket
data starts with a "Dialogue:" string, followed by a timing information
(start and end of the event as string) and a trailing CRLF after each
line. One packet can contain several lines. We'll refer to this layout
as "SSA" or "SSA lines".

In matroska, this markup is not stored as such: it has no "Dialogue:"
prefix, it contains a ReadOrder field, the timing information is not in
the payload, and it doesn't contain the trailing CRLF. See [1] for more
info. We'll refer to this layout as "ASS".

Since we have only one common codec for both formats, the matroska
demuxer is constructing an AVPacket following the "SSA lines" format.
This causes several problems, so it was decided to change this into
clean ASS packets.

Some insight about what is changed or unchanged in this commit:

  CODECS
  ------

  - the decoding process still writes "SSA lines" markup inside the ass
    fields of the subtitles rectangles (sub->rects[n]->ass), which is
    still the current common way of representing decoded subtitles
    markup. It is meant to change later.

  - new ASS codec id: AV_CODEC_ID_ASS (which is different from the
    legacy AV_CODEC_ID_SSA)

  - lavc/assdec: the "ass" decoder is renamed into "ssa" (instead of
    "ass") for consistency with the codec id and allows to add a real
    ass decoder. This ass decoder receives clean ASS lines (so it starts
    with a ReadOrder, is followed by the Layer, etc). We make sure this
    is decoded properly in a new ass-line rectangle of the decoded
    subtitles (the ssa decoder OTOH is doing a simple straightforward
    copy). Using the packet timing instead of data string makes sure the
    ass-line now contains the appropriate timing.

  - lavc/assenc: just like the ass decoder, the "ssa" encoder is renamed
    into "ssa" (instead of "ass") for consistency with the codec id, and
    allows to add a real "ass" encoder.

    One important thing about this encoder is that it only supports one
    ass rectangle: we could have put several dialogue events in the
    AVPacket (separated by a \0 for instance) but this would have cause
    trouble for the muxer which needs not only the start time, but also
    the duration: typically, you have merged events with the same start
    time (stored in the AVPacket->pts) but a different duration. At the
    moment, only the matroska do the merge with the SSA-line codec.

    We will need to make sure all the decoders in the future can't add
    more than one rectangle (and only one Dialogue line in it
    obviously).

  FORMATS
  -------

  - lavf/assenc: the .ass/.ssa muxer can take both SSA and ASS packets.
    In the case of ASS packets as input, it adds the timing based on the
    AVPacket pts and duration, and mux it with "Dialogue:", trailing
    CRLF, etc.

  - lavf/assdec: unchanged; it currently still only outputs SSA-lines
    packets.

  - lavf/mkv: the demuxer can now output ASS packets without the need of
    any "SSA-lines" reconstruction hack. It will become the default at
    next libavformat bump, and the SSA support will be dropped from the
    demuxer. The muxer can take ASS packets since it's muxed normally,
    and still supports the old SSA packets. All the SSA support and
    hacks in Matroska code will be dropped at next lavf bump.

[1]: http://www.matroska.org/technical/specs/subtitles/ssa.html
2013-04-18 23:23:59 +02:00

94 lines
3.6 KiB
C

/*
* SSA/ASS common functions
* Copyright (c) 2010 Aurelien Jacobs <aurel@gnuage.org>
*
* This file is part of FFmpeg.
*
* FFmpeg is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* FFmpeg is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with FFmpeg; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifndef AVCODEC_ASS_H
#define AVCODEC_ASS_H
#include "avcodec.h"
/**
* @name Default values for ASS style
* @{
*/
#define ASS_DEFAULT_FONT "Arial"
#define ASS_DEFAULT_FONT_SIZE 16
#define ASS_DEFAULT_COLOR 0xffffff
#define ASS_DEFAULT_BACK_COLOR 0
#define ASS_DEFAULT_BOLD 0
#define ASS_DEFAULT_ITALIC 0
#define ASS_DEFAULT_UNDERLINE 0
#define ASS_DEFAULT_ALIGNMENT 2
/** @} */
/**
* Generate a suitable AVCodecContext.subtitle_header for SUBTITLE_ASS.
*
* @param avctx pointer to the AVCodecContext
* @param font name of the default font face to use
* @param font_size default font size to use
* @param color default text color to use (ABGR)
* @param back_color default background color to use (ABGR)
* @param bold 1 for bold text, 0 for normal text
* @param italic 1 for italic text, 0 for normal text
* @param underline 1 for underline text, 0 for normal text
* @param alignment position of the text (left, center, top...), defined after
* the layout of the numpad (1-3 sub, 4-6 mid, 7-9 top)
* @return >= 0 on success otherwise an error code <0
*/
int ff_ass_subtitle_header(AVCodecContext *avctx,
const char *font, int font_size,
int color, int back_color,
int bold, int italic, int underline,
int alignment);
/**
* Generate a suitable AVCodecContext.subtitle_header for SUBTITLE_ASS
* with default style.
*
* @param avctx pointer to the AVCodecContext
* @return >= 0 on success otherwise an error code <0
*/
int ff_ass_subtitle_header_default(AVCodecContext *avctx);
/**
* Add an ASS dialog line to an AVSubtitle as a new AVSubtitleRect.
*
* @param sub pointer to the AVSubtitle
* @param dialog ASS dialog to add to sub
* @param ts_start start timestamp for this dialog (in 1/100 second unit)
* @param duration duration for this dialog (in 1/100 second unit), can be -1
* to last until the end of the presentation
* @param raw when set to 2, it indicates that dialog contains an ASS
* dialog line as muxed in Matroska
* when set to 1, it indicates that dialog contains a whole SSA
* dialog line which should be copied as is.
* when set to 0, it indicates that dialog contains only the Text
* part of the ASS dialog line, the rest of the line
* will be generated.
* @return number of characters read from dialog. It can be less than the whole
* length of dialog, if dialog contains several lines of text.
* A negative value indicates an error.
*/
int ff_ass_add_rect(AVSubtitle *sub, const char *dialog,
int ts_start, int duration, int raw);
#endif /* AVCODEC_ASS_H */