webrtc_codecs_playback (webrtc_codecs v0.1.0)

View Source

Show decoded pictures in a window, play decoded audio on the speaker, or write either to a file, through the ffplay and ffmpeg executables running as ports.

{ok, Window} = webrtc_codecs_playback:start(window, #{width => 640, height => 480}),
receive
    {webrtc, Pc, {decoded, Mid, #{format := i420} = Picture}} -> webrtc_codecs_playback:play(Window, Picture)
end.

The window and the speaker are for trying things by hand. A file is for tests: FFmpeg picks the container and the codec from the extension (.mp4, .mkv, .y4m, .wav, ...), and stop/1 returns once the file is complete.

A sink takes one format, given at start. A window or the speaker that cannot keep up drops what play/2 gives it and says so, rather than queue it. A file takes everything: play/2 returns when FFmpeg has taken it, and fails with stalled when FFmpeg has not within write_timeout.

Whatever the program does, stop/1 returns and the program is gone: it is asked to end, then killed.

Summary

Functions

Give a picture or audio to the sink. dropped when a window or the speaker is behind, {error, bad_format} when the media is not in the format the sink was started with, {error, {ended, Status, Text}} when the program has ended by itself, with what it said, {error, stalled} when a file sink did not take the media in time: the program is then killed and the sink takes nothing more.

Start a sink. The process is linked to the caller.

Pictures or chunks of audio given to the sink, and how many it dropped.

Close the sink and end its program. For a file, ok means FFmpeg finished writing it; {error, {not_finalized, Status | killed, Text}} means it ended with an error or had to be killed, and the file may be incomplete.

Types

options()

-type options() ::
          #{width => pos_integer(),
            height => pos_integer(),
            frame_rate => pos_integer(),
            sample_rate => pos_integer(),
            channels => pos_integer(),
            output_options => [string()],
            title => string(),
            write_timeout => pos_integer(),
            finish_timeout => pos_integer(),
            ffmpeg => file:filename_all(),
            ffplay => file:filename_all()}.
  • width, height, frame_rate: of the pictures, default 640, 480, 30
  • sample_rate, channels: of the audio, default 48000, 1
  • output_options: FFmpeg options placed before the name of a file, for example ["-c:v", "libvpx"]
  • title: of the window
  • write_timeout: how long a file sink may take to accept what play/2 gives it, in milliseconds, default 5000
  • finish_timeout: how long stop/1 gives FFmpeg to finish a file, default 15000
  • ffmpeg, ffplay: paths of the executables, default those in PATH

sink()

-type sink() :: window | speaker | {file, video | audio, file:filename_all()}.

Functions

play(Pid, Raw)

-spec play(pid(), webrtc_codecs:picture() | webrtc_codecs:audio()) -> ok | dropped | {error, term()}.

Give a picture or audio to the sink. dropped when a window or the speaker is behind, {error, bad_format} when the media is not in the format the sink was started with, {error, {ended, Status, Text}} when the program has ended by itself, with what it said, {error, stalled} when a file sink did not take the media in time: the program is then killed and the sink takes nothing more.

start(Sink, Opts)

-spec start(sink(), options()) -> {ok, pid()} | {error, term()}.

Start a sink. The process is linked to the caller.

stats(Pid)

-spec stats(pid()) -> #{played := non_neg_integer(), dropped := non_neg_integer()}.

Pictures or chunks of audio given to the sink, and how many it dropped.

stop(Pid)

-spec stop(pid()) -> ok | {error, {not_finalized, integer() | killed, binary()}}.

Close the sink and end its program. For a file, ok means FFmpeg finished writing it; {error, {not_finalized, Status | killed, Text}} means it ended with an error or had to be killed, and the file may be incomplete.