README
¶
mpeg
MPEG-1 Video decoder, MP2 Audio decoder and MPEG-PS Demuxer in pure Go.
Why
This is a simple way to get video playback into your app or game.
MPEG-1 is an old and inefficient codec, but it is still good enough for many use cases. The quality and compression ratio still holds up surprisingly well.
Decoding costs very little CPU time compared to modern video formats. All patents related to MPEG-1 and MP2 have expired, so it is entirely free now.
Examples
- frames - extracts all frames from a video and saves them as JPEG
- player-eb - player using
Ebitengine, also check better, accelerated example - player-rl - player using
raylibwith YUV->RGB conversion done on CPU - player-sdl - player using
SDL2with accelerated YUV->RGB conversion - player-web - player using
WebGLandWebAudio, see live example - player-xv - player using
X11/XVideoandOSS, accelerated
Format
Most MPEG-PS (.mpg) files containing MPEG-1 video (mpeg1video) and MPEG-1 Audio Layer II (mp2) streams should work.
Note that .mpg files can also contain MPEG-2 video, which this library does not support.
You can encode video in a suitable format with FFmpeg:
ffmpeg -i input.mp4 -c:v mpeg1video -q:v 16 -c:a mp2 -format mpeg output.mpg
-q:v sets a fixed video quality with a variable bitrate, where 0 is the highest.
You can use -b:v to set a fixed bitrate instead; e.g. -b:v 2000k for 2000 kbit/s.
Refer to the FFmpeg documentation for more details.
Credits
- pl_mpeg by Dominic Szablewski.
- javampeg1video by Korandi Zoltan.
- kjmp2 by Martin J. Fiedler.
Documentation
¶
Overview ¶
Package mpeg implements MPEG-1 Video decoder, MP2 Audio decoder and MPEG-PS demuxer.
This library provides several interfaces to demux and decode MPEG video and audio data. A high-level MPEG API combines the demuxer, video and audio decoders in an easy-to-use wrapper.
With the high-level interface you have two options to decode video and audio:
1. Decode() and just hand over the delta time since the last call. It will decode everything needed and call your callbacks (specified through Set{Video|Audio}Callback()) any number of times.
2. Use DecodeVideo() and DecodeAudio() to decode exactly one frame of video or audio data at a time. How you handle the synchronization of both streams is up to you.
If you only want to decode video *or* audio through these functions, you should disable the other stream (Set{Video|Audio}Enabled(false))
Video data is decoded into a struct with all 3 planes (Y, Cb, Cr) stored in separate buffers, you can get image.YCbCr via YCbCr() function. You can either convert to image.RGBA on the CPU (slow) via the RGBA() function or do it on the GPU with the following matrix:
mat4 bt601 = mat4(
1.16438, 0.00000, 1.59603, -0.87079,
1.16438, -0.39176, -0.81297, 0.52959,
1.16438, 2.01723, 0.00000, -1.08139,
0, 0, 0, 1
);
gl_FragColor = vec4(y, cb, cr, 1.0) * bt601;
Audio data is decoded into a struct with separate []float32 slices for left and right channel, and with a single []float32 slice with the samples for the left and right channel interleaved. You can convert interleaved samples to byte slice via the Bytes() function.
There should be no need to use the lower level Demux, Video and Audio, if all you want to do is read/decode an MPEG-PS file. However, if you get raw mpeg1video data or raw mp2 audio data from a different source, these functions can be used to decode the raw data directly. Similarly, if you only want to analyze an MPEG-PS file or extract raw video or audio packets from it, you can use the Demux.
Index ¶
- Constants
- Variables
- type Audio
- func (a *Audio) Buffer() *Buffer
- func (a *Audio) Channels() int
- func (a *Audio) Decode() *Samples
- func (a *Audio) HasEnded() bool
- func (a *Audio) HasHeader() bool
- func (a *Audio) Reader() io.Reader
- func (a *Audio) Rewind()
- func (a *Audio) Samplerate() int
- func (a *Audio) SetTime(time float64)
- func (a *Audio) Time() float64
- type AudioFormat
- type AudioFunc
- type Buffer
- func (b *Buffer) Bytes() []byte
- func (b *Buffer) HasEnded() bool
- func (b *Buffer) Index() int
- func (b *Buffer) LoadReaderCallback(buffer *Buffer)
- func (b *Buffer) Remaining() int
- func (b *Buffer) Rewind()
- func (b *Buffer) Seekable() bool
- func (b *Buffer) SetLoadCallback(callback LoadFunc)
- func (b *Buffer) SignalEnd()
- func (b *Buffer) Size() int
- func (b *Buffer) Write(p []byte) int
- type Demux
- func (d *Demux) Buffer() *Buffer
- func (d *Demux) Decode() *Packet
- func (d *Demux) Duration(typ int) float64
- func (d *Demux) HasEnded() bool
- func (d *Demux) HasHeaders() bool
- func (d *Demux) NumAudioStreams() int
- func (d *Demux) NumVideoStreams() int
- func (d *Demux) Rewind()
- func (d *Demux) Seek(seekTime float64, typ int, forceIntra bool) *Packet
- func (d *Demux) StartTime(typ int) float64
- type Frame
- type LoadFunc
- type MPEG
- func (m *MPEG) Audio() *Audio
- func (m *MPEG) AudioEnabled() bool
- func (m *MPEG) AudioFormat() AudioFormat
- func (m *MPEG) AudioLeadTime() time.Duration
- func (m *MPEG) Channels() int
- func (m *MPEG) Decode(tick time.Duration)
- func (m *MPEG) DecodeAudio() *Samples
- func (m *MPEG) DecodeVideo() *Frame
- func (m *MPEG) Done() chan bool
- func (m *MPEG) Duration() time.Duration
- func (m *MPEG) Framerate() float64
- func (m *MPEG) HasEnded() bool
- func (m *MPEG) HasHeaders() bool
- func (m *MPEG) Height() int
- func (m *MPEG) Loop() bool
- func (m *MPEG) NumAudioStreams() int
- func (m *MPEG) NumVideoStreams() int
- func (m *MPEG) Rewind()
- func (m *MPEG) Samplerate() int
- func (m *MPEG) Seek(tm time.Duration, seekExact bool) bool
- func (m *MPEG) SeekFrame(tm time.Duration, seekExact bool) *Frame
- func (m *MPEG) SetAudioCallback(callback AudioFunc)
- func (m *MPEG) SetAudioEnabled(enabled bool)
- func (m *MPEG) SetAudioFormat(format AudioFormat)
- func (m *MPEG) SetAudioLeadTime(leadTime time.Duration)
- func (m *MPEG) SetAudioStream(streamIndex int)
- func (m *MPEG) SetLoop(loop bool)
- func (m *MPEG) SetVideoCallback(callback VideoFunc)
- func (m *MPEG) SetVideoEnabled(enabled bool)
- func (m *MPEG) Time() time.Duration
- func (m *MPEG) Video() *Video
- func (m *MPEG) VideoEnabled() bool
- func (m *MPEG) Width() int
- type Packet
- type Plane
- type Samples
- type SamplesReader
- type Video
- func (v *Video) Buffer() *Buffer
- func (v *Video) Decode() *Frame
- func (v *Video) Framerate() float64
- func (v *Video) HasEnded() bool
- func (v *Video) HasHeader() bool
- func (v *Video) Height() int
- func (v *Video) Rewind()
- func (v *Video) SetNoDelay(noDelay bool)
- func (v *Video) SetTime(time float64)
- func (v *Video) Time() float64
- func (v *Video) Width() int
- type VideoFunc
Constants ¶
const ( PacketInvalidTS = -1 PacketPrivate = 0xBD PacketAudio1 = 0xC0 PacketAudio2 = 0xC1 PacketAudio3 = 0xC2 PacketAudio4 = 0xC3 PacketVideo1 = 0xE0 )
Various packet types.
const (
// SamplesPerFrame is the default count of samples.
SamplesPerFrame = 1152
)
Variables ¶
var (
// BufferSize is the default size for buffer.
BufferSize = 128 * 1024
)
var ErrInvalidHeader = errors.New("invalid MPEG-PS header")
ErrInvalidHeader is the error returned when pack and system headers are not found.
var ErrInvalidMPEG = errors.New("invalid MPEG-PS")
ErrInvalidMPEG is the error returned when the reader is not a valid MPEG Program Stream.
Functions ¶
This section is empty.
Types ¶
type Audio ¶
type Audio struct {
// contains filtered or unexported fields
}
Audio decodes MPEG-1 Audio Layer II (mp2) data into raw samples.
func (*Audio) Decode ¶
Decode decodes and returns one "frame" of audio and advance the internal time by (SamplesPerFrame/samplerate) seconds.
func (*Audio) HasEnded ¶
HasEnded checks whether the file has ended. This will be cleared on rewind.
func (*Audio) HasHeader ¶
HasHeader checks whether a frame header was found, and we can accurately report on samplerate.
func (*Audio) Samplerate ¶
Samplerate returns the sample rate in samples per second.
type AudioFormat ¶ added in v0.2.0
type AudioFormat int
const ( // AudioF32N - 32-bit floating point samples, normalized AudioF32N AudioFormat = iota // AudioF32NLR - 32-bit floating point samples, normalized, separate channels AudioF32NLR // AudioF32 - 32-bit floating point samples AudioF32 // AudioS16 - signed 16-bit samples AudioS16 )
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer provides the data source for all other interfaces.
func (*Buffer) HasEnded ¶
HasEnded checks whether the read position of the buffer is at the end and no more data is expected.
func (*Buffer) LoadReaderCallback ¶
LoadReaderCallback is a callback that is called whenever the buffer needs more data.
func (*Buffer) Remaining ¶
Remaining returns the number of remaining (yet unread) bytes in the buffer. This can be useful to throttle writing.
func (*Buffer) Rewind ¶
func (b *Buffer) Rewind()
Rewind the buffer back to the beginning. When loading from io.ReadSeeker, this also seeks to the beginning.
func (*Buffer) SetLoadCallback ¶
SetLoadCallback sets a callback that is called whenever the buffer needs more data.
func (*Buffer) SignalEnd ¶
func (b *Buffer) SignalEnd()
SignalEnd marks the current byte length as the end of this buffer and signal that no more data is expected to be written to it. This function should be called just after the last Write().
type Demux ¶
type Demux struct {
// contains filtered or unexported fields
}
Demux an MPEG Program Stream (PS) data into separate packages.
func (*Demux) Duration ¶
Duration gets the duration for the specified packet type - i.e. the span between the first PTS and the last PTS in the data source.
func (*Demux) HasEnded ¶
HasEnded checks whether the file has ended. This will be cleared on seeking or rewind.
func (*Demux) HasHeaders ¶
HasHeaders checks whether pack and system headers have been found. This will attempt to read the headers if non are present yet.
func (*Demux) NumAudioStreams ¶
NumAudioStreams returns the number of audio streams found in the system header.
func (*Demux) NumVideoStreams ¶
NumVideoStreams returns the number of video streams found in the system header.
func (*Demux) Seek ¶
Seek seeks to a packet of the specified type with a PTS just before specified time. If forceIntra is true, only packets containing an intra frame will be considered - this only makes sense when the type is video. Note that the specified time is considered 0-based, regardless of the first PTS in the data source.
type Frame ¶
type Frame struct {
Time float64
Width int
Height int
Y Plane
Cb Plane
Cr Plane
// contains filtered or unexported fields
}
Frame represents decoded video frame.
type MPEG ¶
type MPEG struct {
// contains filtered or unexported fields
}
MPEG is high-level interface implementation.
func (*MPEG) AudioEnabled ¶
AudioEnabled checks whether audio decoding is enabled.
func (*MPEG) AudioFormat ¶ added in v0.2.0
func (m *MPEG) AudioFormat() AudioFormat
AudioFormat returns audio format.
func (*MPEG) AudioLeadTime ¶
AudioLeadTime returns the audio lead time in seconds - the time in which audio samples are decoded in advance (or behind) the video decode time.
func (*MPEG) Decode ¶
Decode advances the internal timer by seconds and decode video/audio up to this time. This will call the video_decode_callback and audio_decode_callback any number of times. A frame-skip is not implemented, i.e. everything up to current time will be decoded.
func (*MPEG) DecodeAudio ¶
DecodeAudio decodes and returns one audio frame. Returns nil if no frame could be decoded (either because the source ended or data is corrupt). If you only want to decode audio, you should disable video via SetVideoEnabled(). The returned Samples is valid until the next call to DecodeAudio().
func (*MPEG) DecodeVideo ¶
DecodeVideo decodes and returns one video frame. Returns nil if no frame could be decoded (either because the source ended or data is corrupt). If you only want to decode video, you should disable audio via SetAudioEnabled(). The returned Frame is valid until the next call to DecodeVideo().
func (*MPEG) HasEnded ¶
HasEnded checks whether the file has ended. If looping is enabled, this will always return false.
func (*MPEG) HasHeaders ¶
HasHeaders checks whether we have headers on all available streams, and if we can accurately report the number of video/audio streams, video dimensions, framerate and audio samplerate.
func (*MPEG) NumAudioStreams ¶
NumAudioStreams returns the number of audio streams (0--4) reported in the system header.
func (*MPEG) NumVideoStreams ¶
NumVideoStreams returns the number of video streams (0--1) reported in the system header.
func (*MPEG) Samplerate ¶
Samplerate returns the samplerate of the audio stream in samples per second.
func (*MPEG) Seek ¶
Seek seeks to the specified time, clamped between 0 -- duration. This can only be used when the underlying Buffer is seekable. If seekExact is true this will seek to the exact time, otherwise it will seek to the last intra frame just before the desired time. Exact seeking can be slow, because all frames up to the seeked one have to be decoded on top of the previous intra frame. If seeking succeeds, this function will call the VideoFunc callback exactly once with the target frame. If audio is enabled, it will also call the AudioFunc callback any number of times, until the audioLeadTime is satisfied. Returns true if seeking succeeded or false if no frame could be found.
func (*MPEG) SeekFrame ¶
SeekFrame seeks, similar to Seek(), but will not call the VideoFunc callback, AudioFunc callback or make any attempts to sync audio. Returns the found frame or nil if no frame could be found.
func (*MPEG) SetAudioCallback ¶
SetAudioCallback sets a audio callback.
func (*MPEG) SetAudioEnabled ¶
SetAudioEnabled sets whether audio decoding is enabled.
func (*MPEG) SetAudioFormat ¶ added in v0.2.0
func (m *MPEG) SetAudioFormat(format AudioFormat)
SetAudioFormat sets audio format.
func (*MPEG) SetAudioLeadTime ¶
SetAudioLeadTime sets the audio lead time in seconds. Typically, this should be set to the duration of the buffer of the audio API that you use for output. E.g. for SDL2: (SDL_AudioSpec.samples / samplerate).
func (*MPEG) SetAudioStream ¶
SetAudioStream sets the desired audio stream (0--3). Default 0.
func (*MPEG) SetVideoCallback ¶
SetVideoCallback sets a video callback.
func (*MPEG) SetVideoEnabled ¶
SetVideoEnabled sets whether video decoding is enabled.
func (*MPEG) VideoEnabled ¶
VideoEnabled checks whether video decoding is enabled.
type Packet ¶
Packet is demuxed MPEG PS packet. The Type maps directly to the various MPEG-PES start codes. Pts is the presentation time stamp of the packet in seconds (not all packets have a pts Value).
type Plane ¶
Plane represents decoded video plane. The byte length of the data is width * height. Note that different planes have different sizes: the Luma plane (Y) is double the size of each of the two Chroma planes (Cr, Cb) - i.e. 4 times the byte length. Also note that the size of the plane does *not* denote the size of the displayed frame. The sizes of planes are always rounded up to the nearest macroblock (16px).
type Samples ¶
type Samples struct {
Time float64
S16 []int16
F32 []float32
Left []float32
Right []float32
Interleaved []float32
// contains filtered or unexported fields
}
Samples represents decoded audio samples, stored as normalized (-1, 1) float32, interleaved and in separate channels.
type SamplesReader ¶ added in v0.2.0
type SamplesReader struct {
// contains filtered or unexported fields
}
type Video ¶
type Video struct {
// contains filtered or unexported fields
}
Video decodes MPEG-1 Video (mpeg1) data into raw YCrCb frames.
func (*Video) Decode ¶
Decode decodes and returns one frame of video and advance the internal time by 1/framerate seconds.
func (*Video) HasEnded ¶
HasEnded checks whether the file has ended. This will be cleared on rewind.
func (*Video) HasHeader ¶
HasHeader checks whether a sequence header was found, and we can accurately report on dimensions and framerate.
func (*Video) SetNoDelay ¶
SetNoDelay sets "no delay" mode. When enabled, the decoder assumes that the video does *not* contain any B-Frames. This is useful for reducing lag when streaming.
func (*Video) SetTime ¶
SetTime sets the current internal time in seconds. This is only useful when you manipulate the underlying video buffer and want to enforce a correct timestamps.
Source Files