This class uses the FFmpeg libraries, to write and encode video files and audio files. More...

#include <FFmpegWriter.h>

Inheritance diagram for openshot::FFmpegWriter:

Public Member Functions
void	AddSphericalMetadata (const std::string &projection="equirectangular", float yaw_deg=0.0f, float pitch_deg=0.0f, float roll_deg=0.0f)
	Add spherical (360°) video metadata to the video stream. More...

void	Close ()
	Close the writer. More...

	FFmpegWriter (const std::string &path)
	Constructor for FFmpegWriter. Throws an exception on failure to open path. More...

bool	IsOpen ()
	Determine if writer is open or closed. More...

void	Open ()
	Open writer. More...

void	OutputStreamInfo ()
	Output the ffmpeg info about this format, streams, and codecs (i.e. dump format) More...

void	PrepareStreams ()
	Prepare & initialize streams and open codecs. This method is called automatically by the Open() method if this method has not yet been called. More...

void	ResampleAudio (int sample_rate, int channels)
	Set audio resample options. More...

void	SetAudioOptions (bool has_audio, std::string codec, int sample_rate, int channels, openshot::ChannelLayout channel_layout, int bit_rate)
	Set audio export options. More...

void	SetAudioOptions (std::string codec, int sample_rate, int bit_rate)
	Set audio export options. More...

void	SetOption (openshot::StreamType stream, std::string name, std::string value)
	Set custom options (some codecs accept additional params). This must be called after the PrepareStreams() method, otherwise the streams have not been initialized yet. More...

void	SetVideoOptions (bool has_video, std::string codec, openshot::Fraction fps, int width, int height, openshot::Fraction pixel_ratio, bool interlaced, bool top_field_first, int bit_rate)
	Set video export options. More...

void	SetVideoOptions (std::string codec, int width, int height, openshot::Fraction fps, int bit_rate)
	Set video export options. More...

std::string	Test ()
	Check the current settings without writing a file, and return the result as JSON. More...

void	WriteFrame (openshot::ReaderBase *reader, int64_t start, int64_t length)
	Write a block of frames from a reader. More...

void	WriteFrame (std::shared_ptr< openshot::Frame > frame)
	Add a frame to the stack waiting to be encoded. More...

void	WriteFrameAt (std::shared_ptr< openshot::Frame > frame, int64_t frame_number)
	Add a frame at a specific output video frame number. More...

void	WriteHeader ()
	Write the file header (after the options are set). This method is called automatically by the Open() method if this method has not yet been called. More...

void	WriteTrailer ()
	Write the file trailer (after all frames are written). This is called automatically by the Close() method if this method has not yet been called. More...

Public Member Functions inherited from openshot::WriterBase
void	CopyReaderInfo (openshot::ReaderBase *reader)
	This method copy's the info struct of a reader, and sets the writer with the same info. More...

void	DisplayInfo (std::ostream *out=&std::cout)
	Display file information in the standard output stream (stdout) More...

virtual bool	IsOpen ()=0
	Determine if writer is open or closed. More...

std::string	Json () const
	Generate JSON string of this object. More...

Json::Value	JsonValue () const
	Generate Json::Value for this object. More...

virtual void	Open ()=0
	Open the writer (and start initializing streams) More...

void	SetJson (const std::string value)
	Load JSON string into this object. More...

void	SetJsonValue (const Json::Value root)
	Load Json::Value into this object. More...

virtual void	WriteFrame (openshot::ReaderBase *reader, int64_t start, int64_t length)=0
	This method is required for all derived classes of WriterBase. Write a block of frames from a reader. More...

virtual void	WriteFrame (std::shared_ptr< openshot::Frame > frame)=0
	This method is required for all derived classes of WriterBase. Write a Frame to the video file. More...

	WriterBase ()
	Constructor for WriterBase class, many things are initialized here. More...

virtual	~WriterBase ()=default

Static Public Member Functions
static std::string	GetEncoderInfo (std::string codec_name)
	Describe an encoder's capabilities as JSON. More...

static std::string	GetEncoders (std::string media_type, std::string format_name="")
	List the available encoders as a JSON array. More...

static std::string	GetFormatInfo (std::string format_name)
	Describe an output format as JSON (name, extensions, and default codecs). More...

static std::string	GetFormats ()
	List the file extensions the writer can export to, as a JSON array. More...

static int	IsCodecSupportedByFormat (std::string format_name, std::string codec_name)
	Determine if an output format can store a codec. More...

static bool	IsValidCodec (std::string codec_name)
	Determine if codec name is valid. More...

Additional Inherited Members
Public Attributes inherited from openshot::WriterBase
WriterInfo	info
	Information about the current media file. More...

Detailed Description

This class uses the FFmpeg libraries, to write and encode video files and audio files.

All FFmpeg options can be set using the SetOption() method, and any Reader may be used to generate openshot::Frame objects needed for writing. Be sure to use valid bit rates, frame rates, and sample rates (each format / codec has a limited # of valid options).

 SIMPLE EXAMPLE
 
// Create a reader for a video
openshot::FFmpegReader r("MyAwesomeVideo.webm");
r.Open(); // Open the target reader
 
// Create a writer (which will create a WebM video)
openshot::FFmpegWriter w("/home/jonathan/NewVideo.webm");
 
// Set options
 
// Sample Rate: 44100, Channels: 2, Bitrate: 128000
w.SetAudioOptions(true, "libvorbis", 44100, 2, openshot::ChannelLayout::LAYOUT_STEREO, 128000);
 
// FPS: 24, Size: 720x480, Pixel Ratio: 1/1, Bitrate: 300000
w.SetVideoOptions(true, "libvpx", openshot::Fraction(24,1), 720, 480, openshot::Fraction(1,1), false, false, 300000);
 
// Open the writer
w.Open();
 
// Write all frames from the reader
w.WriteFrame(&r, 1, r.info.video_length);
 
// Close the reader & writer
w.Close();
r.Close();

Here is a more advanced example, which sets some additional (and optional) encoding options.

 ADVANCED WRITER EXAMPLE
 
// Create a reader for a video
openshot::FFmpegReader r("MyAwesomeVideo.webm");
r.Open(); // Open the reader
 
// Create a writer (which will create a WebM video)
openshot::FFmpegWriter w("/home/jonathan/NewVideo.webm");
 
// Set options
 
// Sample Rate: 44100, Channels: 2, Bitrate: 128000
w.SetAudioOptions(true, "libvorbis", 44100, 2, openshot::ChannelLayout::LAYOUT_STEREO, 128000);
 
// FPS: 24, Size: 720x480, Pixel Ratio: 1/1, Bitrate: 300000
w.SetVideoOptions(true, "libvpx", openshot::Fraction(24,1), 720, 480, openshot::Fraction(1,1), false, false, 300000);
 
// Prepare Streams (Optional method that must be called before any SetOption calls)
w.PrepareStreams();
 
// Set some specific encoding options (Optional methods)
w.SetOption(VIDEO_STREAM, "qmin", "2" );
w.SetOption(VIDEO_STREAM, "qmax", "30" );
w.SetOption(VIDEO_STREAM, "crf", "10" );
w.SetOption(VIDEO_STREAM, "rc_min_rate", "2000000" );
w.SetOption(VIDEO_STREAM, "rc_max_rate", "4000000" );
w.SetOption(VIDEO_STREAM, "max_b_frames", "10" );
 
// Write the header of the video file
w.WriteHeader();
 
// Open the writer
w.Open();
 
// Write all frames from the reader
w.WriteFrame(&r, 1, r.info.video_length);
 
// Write the trailer of the video file
w.WriteTrailer();
 
// Close the reader & writer
w.Close();
r.Close();

Definition at line 116 of file FFmpegWriter.h.

Constructor & Destructor Documentation

◆ FFmpegWriter()

FFmpegWriter::FFmpegWriter ( const std::string & path )

Constructor for FFmpegWriter. Throws an exception on failure to open path.

Parameters

path	The file path of the video file you want to open and read

Definition at line 80 of file FFmpegWriter.cpp.

Member Function Documentation

◆ AddSphericalMetadata()

void FFmpegWriter::AddSphericalMetadata	(	const std::string &	projection = `"equirectangular"`,
		float	yaw_deg = `0.0f`,
		float	pitch_deg = `0.0f`,
		float	roll_deg = `0.0f`
	)

Add spherical (360°) video metadata to the video stream.

Parameters

projection	The projection type (e.g., "equirectangular", "cubemap")
yaw_deg	The yaw angle in degrees (horizontal orientation, default 0)
pitch_deg	The pitch angle in degrees (vertical orientation, default 0)
roll_deg	The roll angle in degrees (tilt orientation, default 0)

Definition at line 2927 of file FFmpegWriter.cpp.

◆ Close()

void FFmpegWriter::Close ( )

Close the writer.

Definition at line 1459 of file FFmpegWriter.cpp.

Referenced by openshot::ChunkWriter::Close(), and openshot::ChunkWriter::WriteFrame().

◆ GetEncoderInfo()

std::string FFmpegWriter::GetEncoderInfo ( std::string codec_name )

static

Describe an encoder's capabilities as JSON.

Includes the codec it writes ("codec", i.e. h264), whether it's hardware, lossless, lossy, or intra-only, its quality options, and the sample rates, channel layouts, and formats it accepts. Lists are null when the encoder accepts any value. Unknown encoders return {"found": false}.

Parameters

codec_name The encoder name (i.e. aac, libmp3lame, libx264)

Definition at line 692 of file FFmpegWriter.cpp.

◆ GetEncoders()

std::string FFmpegWriter::GetEncoders	(	std::string	media_type,
		std::string	format_name = `""`
	)

static

List the available encoders as a JSON array.

Parameters

media_type	"audio" or "video"
format_name	Only list encoders this format can store (optional)

Definition at line 855 of file FFmpegWriter.cpp.

◆ GetFormatInfo()

std::string FFmpegWriter::GetFormatInfo ( std::string format_name )

static

Describe an output format as JSON (name, extensions, and default codecs).

The format is matched the same way the writer matches it: by file extension first, and then by FFmpeg's short format name. Unknown formats return {"found": false}.

Parameters

format_name A file extension or format name (i.e. mp4, mkv, webm, matroska)

Definition at line 799 of file FFmpegWriter.cpp.

◆ GetFormats()

std::string FFmpegWriter::GetFormats ( )

static

List the file extensions the writer can export to, as a JSON array.

One entry per extension (i.e. mkv), with its format's name, long name, and default codecs. Only extensions that select that format are listed, matching how the writer picks a format from the file name.

Definition at line 822 of file FFmpegWriter.cpp.

◆ IsCodecSupportedByFormat()

int FFmpegWriter::IsCodecSupportedByFormat	(	std::string	format_name,
		std::string	codec_name
	)

static

Determine if an output format can store a codec.

Returns: 1 if it can, 0 if it can't, and -1 if FFmpeg doesn't know

Parameters

format_name	A file extension or format name (i.e. mp4, mkv, webm, matroska)
codec_name	The encoder name (i.e. aac, libmp3lame, libx264)

Definition at line 881 of file FFmpegWriter.cpp.

◆ IsOpen()

bool openshot::FFmpegWriter::IsOpen ( )

inlinevirtual

Determine if writer is open or closed.

Implements openshot::WriterBase.

Definition at line 216 of file FFmpegWriter.h.

◆ IsValidCodec()

bool FFmpegWriter::IsValidCodec ( std::string codec_name )

static

Determine if codec name is valid.

Definition at line 608 of file FFmpegWriter.cpp.

◆ Open()

void FFmpegWriter::Open ( )

virtual

Open writer.

Implements openshot::WriterBase.

Definition at line 100 of file FFmpegWriter.cpp.

◆ OutputStreamInfo()

void FFmpegWriter::OutputStreamInfo ( )

Output the ffmpeg info about this format, streams, and codecs (i.e. dump format)

Definition at line 2915 of file FFmpegWriter.cpp.

◆ PrepareStreams()

void FFmpegWriter::PrepareStreams ( )

Prepare & initialize streams and open codecs. This method is called automatically by the Open() method if this method has not yet been called.

Definition at line 1008 of file FFmpegWriter.cpp.

Referenced by Open(), and openshot::ChunkWriter::WriteFrame().

◆ ResampleAudio()

void FFmpegWriter::ResampleAudio	(	int	sample_rate,
		int	channels
	)

Set audio resample options.

Parameters

sample_rate	The number of samples per second of the audio
channels	The number of audio channels

Definition at line 2921 of file FFmpegWriter.cpp.

◆ SetAudioOptions() [1/2]

void FFmpegWriter::SetAudioOptions	(	bool	has_audio,
		std::string	codec,
		int	sample_rate,
		int	channels,
		openshot::ChannelLayout	channel_layout,
		int	bit_rate
	)

Set audio export options.

Parameters

has_audio	Does this file need an audio stream?
codec	The codec used to encode the audio for this file
sample_rate	The number of audio samples needed in this file
channels	The number of audio channels needed in this file
channel_layout	The 'layout' of audio channels (i.e. mono, stereo, surround, etc...)
bit_rate	The audio bit rate used during encoding

Note: This is an overloaded function.

Definition at line 292 of file FFmpegWriter.cpp.

Referenced by SetAudioOptions(), and openshot::ChunkWriter::WriteFrame().

◆ SetAudioOptions() [2/2]

void FFmpegWriter::SetAudioOptions	(	std::string	codec,
		int	sample_rate,
		int	bit_rate
	)

Set audio export options.

Enables the stream and configures a default 2-channel stereo layout.

Parameters

codec	The codec used to encode the audio for this file
sample_rate	The number of audio samples needed in this file
bit_rate	The audio bit rate used during encoding

Note: This is an overloaded function.

Definition at line 329 of file FFmpegWriter.cpp.

◆ SetOption()

void FFmpegWriter::SetOption	(	openshot::StreamType	stream,
		std::string	name,
		std::string	value
	)

Set custom options (some codecs accept additional params). This must be called after the PrepareStreams() method, otherwise the streams have not been initialized yet.

Parameters

stream	The stream (openshot::StreamType) this option should apply to
name	The name of the option you want to set (i.e. qmin, qmax, etc...)
value	The new value of this option

Definition at line 339 of file FFmpegWriter.cpp.

◆ SetVideoOptions() [1/2]

void FFmpegWriter::SetVideoOptions	(	bool	has_video,
		std::string	codec,
		openshot::Fraction	fps,
		int	width,
		int	height,
		openshot::Fraction	pixel_ratio,
		bool	interlaced,
		bool	top_field_first,
		int	bit_rate
	)

Set video export options.

Parameters

has_video	Does this file need a video stream
codec	The codec used to encode the images in this video
fps	The number of frames per second
width	The width in pixels of this video
height	The height in pixels of this video
pixel_ratio	The shape of the pixels represented as a openshot::Fraction (1x1 is most common / square pixels)
interlaced	Does this video need to be interlaced?
top_field_first	Which frame should be used as the top field?
bit_rate	The video bit rate used during encoding

Note: This is an overloaded function.

Definition at line 169 of file FFmpegWriter.cpp.

Referenced by SetVideoOptions(), and openshot::ChunkWriter::WriteFrame().

◆ SetVideoOptions() [2/2]

void FFmpegWriter::SetVideoOptions	(	std::string	codec,
		int	width,
		int	height,
		openshot::Fraction	fps,
		int	bit_rate
	)

Set video export options.

Enables the stream and configures non-interlaced video with a 1:1 pixel aspect ratio.

Parameters

codec	The codec used to encode the images in this video
width	The width in pixels of this video
height	The height in pixels of this video
fps	The number of frames per second
bit_rate	The video bit rate used during encoding

Note: This is an overloaded function.

Warning: Observe the argument order, which is consistent with the openshot::Timeline constructor, but differs from the other signature.

Definition at line 282 of file FFmpegWriter.cpp.

◆ Test()

std::string FFmpegWriter::Test ( )

Check the current settings without writing a file, and return the result as JSON.

Call this instead of Open(), after the same options an export would set. It opens the encoders (including hardware encoders) and writes the header to memory, so the format and codecs reject anything they would reject during a real export. FFmpeg's messages are returned instead of printed. The writer can't be used after this call.

Returns {"ok", "stage", "message", "log", "elapsed_ms"}, where stage is "video", "audio", or "header" when the check fails.

Definition at line 923 of file FFmpegWriter.cpp.

◆ WriteFrame() [1/2]

void FFmpegWriter::WriteFrame	(	openshot::ReaderBase *	reader,
		int64_t	start,
		int64_t	length
	)

virtual

Write a block of frames from a reader.

Parameters

reader	A openshot::ReaderBase object which will provide frames to be written
start	The starting frame number of the reader
length	The number of frames to write

Note: This is an overloaded function.

Implements openshot::WriterBase.

Definition at line 1163 of file FFmpegWriter.cpp.

◆ WriteFrame() [2/2]

void FFmpegWriter::WriteFrame ( std::shared_ptr< openshot::Frame > frame )

virtual

Add a frame to the stack waiting to be encoded.

Parameters

frame The openshot::Frame object to write to this image

Note: This is an overloaded function.

Implements openshot::WriterBase.

Definition at line 1071 of file FFmpegWriter.cpp.

Referenced by openshot::ChunkWriter::Close(), WriteFrame(), and openshot::ChunkWriter::WriteFrame().

◆ WriteFrameAt()

void FFmpegWriter::WriteFrameAt	(	std::shared_ptr< openshot::Frame >	frame,
		int64_t	frame_number
	)

Add a frame at a specific output video frame number.

Parameters

frame	The openshot::Frame object to write
frame_number	The 1-based output video frame number used for video PTS

Note: Audio is still written sequentially. This overload is intended for timestamped live video capture where missing frame numbers represent gaps.

Definition at line 1088 of file FFmpegWriter.cpp.

◆ WriteHeader()

void FFmpegWriter::WriteHeader ( )

Write the file header (after the options are set). This method is called automatically by the Open() method if this method has not yet been called.

Definition at line 1025 of file FFmpegWriter.cpp.

Referenced by Open(), and openshot::ChunkWriter::WriteFrame().

◆ WriteTrailer()

void FFmpegWriter::WriteTrailer ( )

Write the file trailer (after all frames are written). This is called automatically by the Close() method if this method has not yet been called.

Definition at line 1180 of file FFmpegWriter.cpp.

Referenced by openshot::ChunkWriter::Close(), Close(), and openshot::ChunkWriter::WriteFrame().

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FFmpegWriter()

Member Function Documentation

◆ AddSphericalMetadata()

◆ Close()

◆ GetEncoderInfo()

◆ GetEncoders()

◆ GetFormatInfo()

◆ GetFormats()

◆ IsCodecSupportedByFormat()

◆ IsOpen()

◆ IsValidCodec()

◆ Open()

◆ OutputStreamInfo()

◆ PrepareStreams()

◆ ResampleAudio()

◆ SetAudioOptions() [1/2]

◆ SetAudioOptions() [2/2]

◆ SetOption()

◆ SetVideoOptions() [1/2]

◆ SetVideoOptions() [2/2]

◆ Test()

◆ WriteFrame() [1/2]

◆ WriteFrame() [2/2]

◆ WriteFrameAt()

◆ WriteHeader()

◆ WriteTrailer()