caption-screen.h File Reference

Turns the caption PES packets into lines of text. More...

#include "caption-common.h"

Include dependency graph for caption-screen.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	CaptionLine_t

Macros
#define	CAPTION_SCREEN_MAX_LINES   16
#define	CAPTION_SCREEN_LINE_LEN   256

Typedefs
typedef void(*	CaptionScreenLineCallback_t) (const CaptionLine_t *line, void *userdata)
typedef struct CaptionScreen_s	CaptionScreen_t

Functions
CaptionScreen_t *	caption_screen_new (CaptionScreenLineCallback_t callback, void *userdata)
void	caption_screen_free (CaptionScreen_t *screen)
bool	caption_screen_push_pes (CaptionScreen_t *screen, const uint8_t *pes, size_t len)
void	caption_screen_flush (CaptionScreen_t *screen)
bool	caption_screen_line_continues (const char *line, const char *prefix)

Detailed Description

Turns the caption PES packets into lines of text.

Author

Jorge Pereira jpere.nosp@m.iran.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

This is the easiest way to use the library: you give it the whole PES of the caption PID (see ts-demux.h), it does all the processing (packet_pes_load(), caption_data_load(), caption_management_load() and caption_closed_run()) and hands every ready caption line, in UTF-8, to a callback.

How the lines are built

• The APR (0x0d) and APS (0x1c) commands break the line; the padding spaces at the end of each line are removed.
• Each PES redraws the whole screen. Live captions (roll-up) resend the same line every few letters, so a line is only delivered when it leaves the screen, that is, when no line of the new screen is a continuation of it.
• The comparison ignores accents: the broadcaster often sends the letter without the accent and fixes it on the next screen (e.g. "ESPECI" → "ESPECÍFICO").
• The time of each line is the PTS of the PES where it showed up, relative to the first caption PTS received.

Example:

static void
on_line (const CaptionLine_t *line, void *userdata)
{
  printf ("[%u ms] %s\n", line->start_ms, line->text);
}
 
CaptionScreen_t *screen = caption_screen_new (on_line, NULL);
 
// for each whole PES of the caption PID:
caption_screen_push_pes (screen, pes, len);
 
caption_screen_flush (screen); // delivers the lines that are still on the screen
caption_screen_free (screen);

Warning

The hooks from caption-hooking.h are global: caption_screen_push_pes() registers its own hooks, replacing whatever is registered. For the same reason, it is not safe to use the library on more than one thread at the same time.

Definition in file caption-screen.h.

Macro Definition Documentation

CAPTION_SCREEN_MAX_LINES

#define CAPTION_SCREEN_MAX_LINES   16

Max number of lines kept on the screen.

Definition at line 53 of file caption-screen.h.

CAPTION_SCREEN_LINE_LEN

#define CAPTION_SCREEN_LINE_LEN   256

Max size of a line, in UTF-8 bytes (including the '\0').

Definition at line 56 of file caption-screen.h.

Typedef Documentation

CaptionScreenLineCallback_t

typedef void(* CaptionScreenLineCallback_t) (const CaptionLine_t *line, void *userdata)

Callback called for each finished caption line.

Parameters

line	The line. Only valid during the call.
userdata	Pointer given to caption_screen_new().

Definition at line 72 of file caption-screen.h.

CaptionScreen_t

typedef struct CaptionScreen_s CaptionScreen_t

Caption screen. Opaque struct, created by caption_screen_new().

Definition at line 78 of file caption-screen.h.

Function Documentation

caption_screen_new()

CaptionScreen_t * caption_screen_new	(	CaptionScreenLineCallback_t	callback,
		void *	userdata
	)

Creates a caption screen.

Parameters

callback	Called for each finished line.
userdata	Passed on to the callback.

Returns

The screen, or NULL if out of memory. Free with caption_screen_free().

caption_screen_free()

void caption_screen_free

(

CaptionScreen_t *

screen

)

Frees the screen. Does not call caption_screen_flush().

Parameters

screen

Screen created by caption_screen_new(). NULL is fine.

caption_screen_push_pes()

bool caption_screen_push_pes	(	CaptionScreen_t *	screen,
		const uint8_t *	pes,
		size_t	len
	)

Processes a whole PES from the caption PID.

Invalid PES, with a bad CRC, or that are not "caption statement data" (for example, the "caption management data") are ignored.

Parameters

screen	Screen created by caption_screen_new().
pes	Whole PES, starting at the packet_start_code_prefix (00 00 01).
len	Size of pes in bytes.

Returns

TRUE if the PES had caption text and was processed.

caption_screen_flush()

void caption_screen_flush

(

CaptionScreen_t *

screen

)

Delivers all the lines that are still on the screen and clears the screen. Call it at the end of the file.

Parameters

screen

Screen created by caption_screen_new().

caption_screen_line_continues()

bool caption_screen_line_continues	(	const char *	line,
		const char *	prefix
	)

Checks if line starts with prefix, ignoring the accents of the Latin-1 letters (U+00C0 to U+00FF). For example, "ESPECÍFICO" starts with "ESPECI".

Parameters

line	UTF-8 text.
prefix	UTF-8 prefix.

Returns

TRUE if line starts with prefix.