summaryrefslogtreecommitdiff
path: root/docs/av_api.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/av_api.md')
-rw-r--r--docs/av_api.md30
1 files changed, 21 insertions, 9 deletions
diff --git a/docs/av_api.md b/docs/av_api.md
index 63e6801f..6cd7f79a 100644
--- a/docs/av_api.md
+++ b/docs/av_api.md
@@ -110,12 +110,15 @@ Return value:
110rtp_session_t* - pointer to a newly created rtp session handler. 110rtp_session_t* - pointer to a newly created rtp session handler.
111``` 111```
112 112
113How to handle rtp session: 113###How to handle rtp session:
114Take a look at 114Take a look at
115```
115void* phone_handle_media_transport_poll ( void* _hmtc_args_p ) in phone.c 116void* phone_handle_media_transport_poll ( void* _hmtc_args_p ) in phone.c
117```
116on example. Basically what you do is just receive a message via: 118on example. Basically what you do is just receive a message via:
117 119```
118struct rtp_msg_s* rtp_recv_msg ( rtp_session_t* _session ); 120struct rtp_msg_s* rtp_recv_msg ( rtp_session_t* _session );
121```
119 122
120and then you use payload within the rtp_msg_s struct. Don't forget to deallocate it with: 123and then you use payload within the rtp_msg_s struct. Don't forget to deallocate it with:
121void rtp_free_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg ); 124void rtp_free_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg );
@@ -124,17 +127,20 @@ Receiving should be thread safe so don't worry about that.
124When you capture and encode a payload you want to send it ( obviously ). 127When you capture and encode a payload you want to send it ( obviously ).
125 128
126first create a new message with: 129first create a new message with:
130```
127struct rtp_msg_s* rtp_msg_new ( rtp_session_t* _session, const uint8_t* _data, uint32_t _length ); 131struct rtp_msg_s* rtp_msg_new ( rtp_session_t* _session, const uint8_t* _data, uint32_t _length );
132```
128 133
129and then send it with: 134and then send it with:
135```
130int rtp_send_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg, void* _core_handler ); 136int rtp_send_msg ( rtp_session_t* _session, struct rtp_msg_s* _msg, void* _core_handler );
137```
131 138
132_core_handler is the same network handler as in msi_session_s struct. 139_core_handler is the same network handler as in msi_session_s struct.
133 140
134 141
135
136##A/V initialization: 142##A/V initialization:
137 143```
138int init_receive_audio(codec_state *cs); 144int init_receive_audio(codec_state *cs);
139int init_receive_video(codec_state *cs); 145int init_receive_video(codec_state *cs);
140Initialises the A/V decoders. On failure it will print the reason and return 0. On success it will return 1. 146Initialises the A/V decoders. On failure it will print the reason and return 0. On success it will return 1.
@@ -148,30 +154,36 @@ int video_encoder_refresh(codec_state *cs, int bps);
148Reinitialises the video encoder with a new bitrate. ffmpeg does not expose the needed VP8 feature to change the bitrate on the fly, so this serves as a workaround. 154Reinitialises the video encoder with a new bitrate. ffmpeg does not expose the needed VP8 feature to change the bitrate on the fly, so this serves as a workaround.
149In the future, VP8 should be used directly and ffmpeg should be dropped from the dependencies. 155In the future, VP8 should be used directly and ffmpeg should be dropped from the dependencies.
150The variable bps is the required bitrate in bits per second. 156The variable bps is the required bitrate in bits per second.
151 157```
152 158
153 159
154###A/V encoding/decoding: 160###A/V encoding/decoding:
155 161```
156void *encode_video_thread(void *arg); 162void *encode_video_thread(void *arg);
163```
157Spawns the video encoding thread. The argument should hold a pointer to a codec_state. 164Spawns the video encoding thread. The argument should hold a pointer to a codec_state.
158This function should only be called if video encoding is supported (when init_send_video returns 1). 165This function should only be called if video encoding is supported (when init_send_video returns 1).
159Each video frame gets encoded into a packet, which is sent via RTP. Every 60 frames a new bidirectional interframe is encoded. 166Each video frame gets encoded into a packet, which is sent via RTP. Every 60 frames a new bidirectional interframe is encoded.
160 167```
161void *encode_audio_thread(void *arg); 168void *encode_audio_thread(void *arg);
169```
162Spawns the audio encoding thread. The argument should hold a pointer to a codec_state. 170Spawns the audio encoding thread. The argument should hold a pointer to a codec_state.
163This function should only be called if audio encoding is supported (when init_send_audio returns 1). 171This function should only be called if audio encoding is supported (when init_send_audio returns 1).
164Audio frames are read from the selected audio capture device during intitialisation. This audio capturing can be rerouted to a different device on the fly. 172Audio frames are read from the selected audio capture device during intitialisation. This audio capturing can be rerouted to a different device on the fly.
165Each audio frame is encoded into a packet, and sent via RTP. All audio frames have the same amount of samples, which is defined in AV_codec.h. 173Each audio frame is encoded into a packet, and sent via RTP. All audio frames have the same amount of samples, which is defined in AV_codec.h.
166 174```
167int video_decoder_refresh(codec_state *cs, int width, int height); 175int video_decoder_refresh(codec_state *cs, int width, int height);
176```
168Sets the SDL window dimensions and creates a pixel buffer with the requested size. It also creates a scaling context, which will be used to convert the input image format to YUV420P. 177Sets the SDL window dimensions and creates a pixel buffer with the requested size. It also creates a scaling context, which will be used to convert the input image format to YUV420P.
169 178
179```
170void *decode_video_thread(void *arg); 180void *decode_video_thread(void *arg);
181```
171Spawns a video decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised video decoder. 182Spawns a video decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised video decoder.
172This function reads video packets and feeds them to the video decoder. If the video frame's resolution has changed, video_decoder_refresh() is called. Afterwards, the frame is displayed on the SDL window. 183This function reads video packets and feeds them to the video decoder. If the video frame's resolution has changed, video_decoder_refresh() is called. Afterwards, the frame is displayed on the SDL window.
173 184```
174void *decode_audio_thread(void *arg); 185void *decode_audio_thread(void *arg);
186```
175Spawns an audio decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised audio decoder. 187Spawns an audio decoding thread. The argument should hold a pointer to a codec_state. The codec_state is assumed to contain a successfully initialised audio decoder.
176All received audio packets are pushed into a jitter buffer and are reordered. If there is a missing packet, or a packet has arrived too late, it is treated as a lost packet and the audio decoder is informed of the packet loss. The audio decoder will then try to reconstruct the lost packet, based on information from previous packets. 188All received audio packets are pushed into a jitter buffer and are reordered. If there is a missing packet, or a packet has arrived too late, it is treated as a lost packet and the audio decoder is informed of the packet loss. The audio decoder will then try to reconstruct the lost packet, based on information from previous packets.
177Audio is played on the default OpenAL output device. 189Audio is played on the default OpenAL output device.