/src/pjsip/pjmedia/include/pjmedia/avi_stream.h

Source
/* 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
#ifndef __PJMEDIA_AVI_STREAM_H__
#define __PJMEDIA_AVI_STREAM_H__

/**
 * @file avi_stream.h
 * @brief AVI file player.
 */
#include <pjmedia/port.h>


PJ_BEGIN_DECL


/**
 * @defgroup PJMEDIA_AVI_FILE_PLAY AVI File Player
 * @ingroup PJMEDIA_PORT
 * @brief Video and audio playback from AVI file
 * @{
 */

/**
 * AVI file player options.
 */
enum pjmedia_avi_file_player_option
{
    /**
     * Tell the file player to return NULL frame when the whole
     * file has been played.
     */
    PJMEDIA_AVI_FILE_NO_LOOP = 1,

    /**
     * Set the file player to permit independent playback of audio and
     * video streams without synchronization.
     */
    PJMEDIA_AVI_FILE_NO_SYNC = 2
};

/**
 * AVI stream data type.
 */
typedef pjmedia_port pjmedia_avi_stream;

/**
 * Opaque data type for AVI streams. AVI streams is a collection of
 * zero or more AVI stream.
 */
typedef struct pjmedia_avi_streams pjmedia_avi_streams;

struct pjmedia_avi_streams
{
    pj_pool_t       *pool;
    unsigned         num_streams;
    pjmedia_port   **streams;
};

/**
 * Create avi streams to play an AVI file. AVI player supports 
 * reading AVI file with uncompressed video format and 
 * 16 bit PCM or compressed G.711 A-law/U-law audio format.
 *
 * By default, avi streams will loop the file playback and synchronize
 * audio and video streams. To change this behavior, use the flags parameter.
 *
 * When synchronization is enabled, the file player will wait for all
 * media streams to reach the end of file before rewinding the file.
 *
 * @param pool          Pool to create the streams.
 * @param filename      File name to open.
 * @param flags         Avi streams creation flags, bitmask combination of
 *                      #pjmedia_avi_file_player_option.
 * @param p_streams     Pointer to receive the avi streams instance.
 *
 * @return              PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjmedia_avi_player_create_streams(pj_pool_t *pool,
                                  const char *filename,
                                  unsigned flags,
                                  pjmedia_avi_streams **p_streams);

/**
 * Get the number of AVI stream.
 *
 * @param streams       The AVI streams.
 *
 * @return              The number of AVI stream.
 */
PJ_DECL(unsigned)
pjmedia_avi_streams_get_num_streams(pjmedia_avi_streams *streams);

/**
 * Get the number of AVI stream with a certain media type.
 *
 * @param streams       The AVI streams.
 * @param media_type    The media type of the stream.
 *
 * @return              The number of AVI stream.
 */
PJ_DECL(unsigned)
pjmedia_avi_streams_get_num_streams_by_media(pjmedia_avi_streams *streams,
                                             pjmedia_type media_type);

/**
 * Return the idx-th stream of the AVI streams.
 *
 * @param streams       The AVI streams.
 * @param idx           The stream index.
 *
 * @return              The AVI stream or NULL if it does not exist.
 */
PJ_DECL(pjmedia_avi_stream *)
pjmedia_avi_streams_get_stream(pjmedia_avi_streams *streams,
                               unsigned idx);

/**
 * Return an AVI stream with a certain media type from the AVI streams.
 *
 * @param streams       The AVI streams.
 * @param start_idx     The starting index.
 * @param media_type    The media type of the stream.
 *
 * @return              The AVI stream or NULL if it does not exist.
 */
PJ_DECL(pjmedia_avi_stream *)
pjmedia_avi_streams_get_stream_by_media(pjmedia_avi_streams *streams,
                                        unsigned start_idx,
                                        pjmedia_type media_type);

/**
 * Return the media port of an AVI stream.
 *
 * @param stream        The AVI stream.
 *
 * @return              The media port.
 */
PJ_INLINE(pjmedia_port *)
pjmedia_avi_stream_get_port(pjmedia_avi_stream *stream)
{
    return (pjmedia_port *)stream;
}

/**
 * Get the data length, in bytes.
 *
 * @param stream        The AVI stream.
 *
 * @return              The length of the data, in bytes. Upon error it will
 *                      return negative value.
 */
PJ_DECL(pj_ssize_t) pjmedia_avi_stream_get_len(pjmedia_avi_stream *stream);


#if !DEPRECATED_FOR_TICKET_2251
/**
 * Register a callback to be called when the file reading has reached the
 * end of file. If the file is set to play repeatedly, then the callback
 * will be called multiple times. Note that only one callback can be 
 * registered for each AVI stream.
 *
 * @param stream        The AVI stream.
 * @param user_data     User data to be specified in the callback
 * @param cb            Callback to be called. If the callback returns non-
 *                      PJ_SUCCESS, the playback will stop. Note that if
 *                      application destroys the file port in the callback,
 *                      it must return non-PJ_SUCCESS here.
 *
 * @return              PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_avi_stream_set_eof_cb(pjmedia_avi_stream *stream,
                              void *user_data,
                              pj_status_t (*cb)(pjmedia_avi_stream *stream,
                                                void *usr_data));
#endif


/**
 * Register a callback to be called when the file reading has reached the
 * end of file. If the file is set to play repeatedly, then the callback
 * will be called multiple times. Note that only one callback can be 
 * registered for each AVI stream.
 *
 * @param stream        The AVI stream.
 * @param user_data     User data to be specified in the callback
 * @param cb            Callback to be called. Note that if
 *                      application wishes to stop the playback, it
 *                      can disconnect the port in the callback, and
 *                      only after all connections have been removed
 *                      could the application safely destroy the port.
 *
 * @return              PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_avi_stream_set_eof_cb2(pjmedia_avi_stream *stream,
                               void *user_data,
                               void (*cb)(pjmedia_avi_stream *stream,
                                          void *usr_data));


/**
 * @}
 */

/**
 * @defgroup PJMEDIA_AVI_FILE_WRITE AVI File Writer
 * @ingroup PJMEDIA_PORT
 * @brief Video and audio recording to AVI file
 * @{
 */

/**
 * Create avi streams to write to an AVI file. AVI writer supports
 * recording AVI file with uncompressed video format and
 * 16 bit PCM.
 *
 * Note that video recording file size can grow very quickly, and
 * once it reaches the maximum size specified, the file will be
 * automatically closed and the callback (if any) will be called.
 *
 * @param pool          Pool to create the streams.
 * @param filename      File name to write to.
 * @param max_fsize     Maximum file size.
 * @param num_streams   Number of streams to write. Typically this should be
 *                      2, one for video, and one for audio.
 * @param format        The format of the streams.
 * @param flags         Avi streams creation flags. Currently must be zero.
 * @param p_streams     Pointer to receive the avi streams instance.
 *
 * @return              PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjmedia_avi_writer_create_streams(pj_pool_t *pool,
                                  const char *filename,
                                  pj_uint32_t max_fsize,
                                  unsigned num_streams,
                                  const pjmedia_format format[],
                                  unsigned flags,
                                  pjmedia_avi_streams **p_streams);


/**
 * Register the callback to be called when the file writing has reached
 * maximum size.
 *
 * @param streams       The AVI writer streams.
 * @param user_data     User data to be specified in the callback, and will be
 *                      given on the callback.
 * @param cb            Callback to be called.
 *
 * @return              PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjmedia_avi_streams_set_cb(pjmedia_avi_streams *streams,
                           void *user_data,
                           void (*cb)(pjmedia_avi_streams *streams,
                                      void *usr_data));


PJ_END_DECL


#endif  /* __PJMEDIA_AVI_STREAM_H__ */

Coverage Report

Created: 2025-10-28 06:39

Line	Count	Source
1		/*
2		* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
3		*
4		* This program is free software; you can redistribute it and/or modify
5		* it under the terms of the GNU General Public License as published by
6		* the Free Software Foundation; either version 2 of the License, or
7		* (at your option) any later version.
8		*
9		* This program is distributed in the hope that it will be useful,
10		* but WITHOUT ANY WARRANTY; without even the implied warranty of
11		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12		* GNU General Public License for more details.
13		*
14		* You should have received a copy of the GNU General Public License
15		* along with this program; if not, write to the Free Software
16		* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17		*/
18		#ifndef __PJMEDIA_AVI_STREAM_H__
19		#define __PJMEDIA_AVI_STREAM_H__
20
21		/**
22		* @file avi_stream.h
23		* @brief AVI file player.
24		*/
25		#include <pjmedia/port.h>
26
27
28		PJ_BEGIN_DECL
29
30
31		/**
32		* @defgroup PJMEDIA_AVI_FILE_PLAY AVI File Player
33		* @ingroup PJMEDIA_PORT
34		* @brief Video and audio playback from AVI file
35		* @{
36		*/
37
38		/**
39		* AVI file player options.
40		*/
41		enum pjmedia_avi_file_player_option
42		{
43		/**
44		* Tell the file player to return NULL frame when the whole
45		* file has been played.
46		*/
47		PJMEDIA_AVI_FILE_NO_LOOP = 1,
48
49		/**
50		* Set the file player to permit independent playback of audio and
51		* video streams without synchronization.
52		*/
53		PJMEDIA_AVI_FILE_NO_SYNC = 2
54		};
55
56		/**
57		* AVI stream data type.
58		*/
59		typedef pjmedia_port pjmedia_avi_stream;
60
61		/**
62		* Opaque data type for AVI streams. AVI streams is a collection of
63		* zero or more AVI stream.
64		*/
65		typedef struct pjmedia_avi_streams pjmedia_avi_streams;
66
67		struct pjmedia_avi_streams
68		{
69		pj_pool_t *pool;
70		unsigned num_streams;
71		pjmedia_port **streams;
72		};
73
74		/**
75		* Create avi streams to play an AVI file. AVI player supports
76		* reading AVI file with uncompressed video format and
77		* 16 bit PCM or compressed G.711 A-law/U-law audio format.
78		*
79		* By default, avi streams will loop the file playback and synchronize
80		* audio and video streams. To change this behavior, use the flags parameter.
81		*
82		* When synchronization is enabled, the file player will wait for all
83		* media streams to reach the end of file before rewinding the file.
84		*
85		* @param pool Pool to create the streams.
86		* @param filename File name to open.
87		* @param flags Avi streams creation flags, bitmask combination of
88		* #pjmedia_avi_file_player_option.
89		* @param p_streams Pointer to receive the avi streams instance.
90		*
91		* @return PJ_SUCCESS on success.
92		*/
93		PJ_DECL(pj_status_t)
94		pjmedia_avi_player_create_streams(pj_pool_t *pool,
95		const char *filename,
96		unsigned flags,
97		pjmedia_avi_streams **p_streams);
98
99		/**
100		* Get the number of AVI stream.
101		*
102		* @param streams The AVI streams.
103		*
104		* @return The number of AVI stream.
105		*/
106		PJ_DECL(unsigned)
107		pjmedia_avi_streams_get_num_streams(pjmedia_avi_streams *streams);
108
109		/**
110		* Get the number of AVI stream with a certain media type.
111		*
112		* @param streams The AVI streams.
113		* @param media_type The media type of the stream.
114		*
115		* @return The number of AVI stream.
116		*/
117		PJ_DECL(unsigned)
118		pjmedia_avi_streams_get_num_streams_by_media(pjmedia_avi_streams *streams,
119		pjmedia_type media_type);
120
121		/**
122		* Return the idx-th stream of the AVI streams.
123		*
124		* @param streams The AVI streams.
125		* @param idx The stream index.
126		*
127		* @return The AVI stream or NULL if it does not exist.
128		*/
129		PJ_DECL(pjmedia_avi_stream *)
130		pjmedia_avi_streams_get_stream(pjmedia_avi_streams *streams,
131		unsigned idx);
132
133		/**
134		* Return an AVI stream with a certain media type from the AVI streams.
135		*
136		* @param streams The AVI streams.
137		* @param start_idx The starting index.
138		* @param media_type The media type of the stream.
139		*
140		* @return The AVI stream or NULL if it does not exist.
141		*/
142		PJ_DECL(pjmedia_avi_stream *)
143		pjmedia_avi_streams_get_stream_by_media(pjmedia_avi_streams *streams,
144		unsigned start_idx,
145		pjmedia_type media_type);
146
147		/**
148		* Return the media port of an AVI stream.
149		*
150		* @param stream The AVI stream.
151		*
152		* @return The media port.
153		*/
154		PJ_INLINE(pjmedia_port *)
155		pjmedia_avi_stream_get_port(pjmedia_avi_stream *stream)
156	0	{
157	0	return (pjmedia_port *)stream;
158	0	}
159
160		/**
161		* Get the data length, in bytes.
162		*
163		* @param stream The AVI stream.
164		*
165		* @return The length of the data, in bytes. Upon error it will
166		* return negative value.
167		*/
168		PJ_DECL(pj_ssize_t) pjmedia_avi_stream_get_len(pjmedia_avi_stream *stream);
169
170
171		#if !DEPRECATED_FOR_TICKET_2251
172		/**
173		* Register a callback to be called when the file reading has reached the
174		* end of file. If the file is set to play repeatedly, then the callback
175		* will be called multiple times. Note that only one callback can be
176		* registered for each AVI stream.
177		*
178		* @param stream The AVI stream.
179		* @param user_data User data to be specified in the callback
180		* @param cb Callback to be called. If the callback returns non-
181		* PJ_SUCCESS, the playback will stop. Note that if
182		* application destroys the file port in the callback,
183		* it must return non-PJ_SUCCESS here.
184		*
185		* @return PJ_SUCCESS on success.
186		*/
187		PJ_DECL(pj_status_t)
188		pjmedia_avi_stream_set_eof_cb(pjmedia_avi_stream *stream,
189		void *user_data,
190		pj_status_t (cb)(pjmedia_avi_stream stream,
191		void *usr_data));
192		#endif
193
194
195		/**
196		* Register a callback to be called when the file reading has reached the
197		* end of file. If the file is set to play repeatedly, then the callback
198		* will be called multiple times. Note that only one callback can be
199		* registered for each AVI stream.
200		*
201		* @param stream The AVI stream.
202		* @param user_data User data to be specified in the callback
203		* @param cb Callback to be called. Note that if
204		* application wishes to stop the playback, it
205		* can disconnect the port in the callback, and
206		* only after all connections have been removed
207		* could the application safely destroy the port.
208		*
209		* @return PJ_SUCCESS on success.
210		*/
211		PJ_DECL(pj_status_t)
212		pjmedia_avi_stream_set_eof_cb2(pjmedia_avi_stream *stream,
213		void *user_data,
214		void (cb)(pjmedia_avi_stream stream,
215		void *usr_data));
216
217
218		/**
219		* @}
220		*/
221
222		/**
223		* @defgroup PJMEDIA_AVI_FILE_WRITE AVI File Writer
224		* @ingroup PJMEDIA_PORT
225		* @brief Video and audio recording to AVI file
226		* @{
227		*/
228
229		/**
230		* Create avi streams to write to an AVI file. AVI writer supports
231		* recording AVI file with uncompressed video format and
232		* 16 bit PCM.
233		*
234		* Note that video recording file size can grow very quickly, and
235		* once it reaches the maximum size specified, the file will be
236		* automatically closed and the callback (if any) will be called.
237		*
238		* @param pool Pool to create the streams.
239		* @param filename File name to write to.
240		* @param max_fsize Maximum file size.
241		* @param num_streams Number of streams to write. Typically this should be
242		* 2, one for video, and one for audio.
243		* @param format The format of the streams.
244		* @param flags Avi streams creation flags. Currently must be zero.
245		* @param p_streams Pointer to receive the avi streams instance.
246		*
247		* @return PJ_SUCCESS on success.
248		*/
249		PJ_DECL(pj_status_t)
250		pjmedia_avi_writer_create_streams(pj_pool_t *pool,
251		const char *filename,
252		pj_uint32_t max_fsize,
253		unsigned num_streams,
254		const pjmedia_format format[],
255		unsigned flags,
256		pjmedia_avi_streams **p_streams);
257
258
259		/**
260		* Register the callback to be called when the file writing has reached
261		* maximum size.
262		*
263		* @param streams The AVI writer streams.
264		* @param user_data User data to be specified in the callback, and will be
265		* given on the callback.
266		* @param cb Callback to be called.
267		*
268		* @return PJ_SUCCESS on success.
269		*/
270		PJ_DECL(pj_status_t)
271		pjmedia_avi_streams_set_cb(pjmedia_avi_streams *streams,
272		void *user_data,
273		void (cb)(pjmedia_avi_streams streams,
274		void *usr_data));
275
276
277		PJ_END_DECL
278
279
280		#endif /* __PJMEDIA_AVI_STREAM_H__ */