av.h¶
#include <primo/codecs/av.h>
Includes¶
primo/platform/reference.hprimo/platform/error.h
Classes¶
Name |
Description |
|---|---|
AudioStreamInfo describes an elementary audio stream. |
|
A buffer for media data. |
|
MediaSample represents one or more samples of audio or video data. |
|
MetaAttribute describes a textual meta information that is part of an audio or video file. |
|
MetaAttributeList represents the meta attributes inside a Metadata object. |
|
MetaPicture describes a meta image that is part of an audio or video file. |
|
MetaPictureList represents the meta pictures inside a Metadata object. |
|
Metadata describes meta information that is part of an audio or video file. |
|
Provides properties and operations that are common for all elementary streams. |
|
StreamInfoEnum is a read-only collection of StreamInfo objects. |
|
VideoStreamInfo describes an elementary video stream. |
Namespaces¶
primoprimo::codecsprimo::codecs::AlphaCompositingModeprimo::codecs::AudioChannelFlagsprimo::codecs::BitrateModeprimo::codecs::CodecErrorprimo::codecs::ColorFormatprimo::codecs::DeinterlacingMethodprimo::codecs::FrameTypeprimo::codecs::H264DeblockingFilterprimo::codecs::H264DirectPredModeprimo::codecs::H264EntropyCodingModeprimo::codecs::H264MeMethodprimo::codecs::H264MeSplitModeprimo::codecs::H264PicCodingTypeprimo::codecs::H264Profileprimo::codecs::H264RateControlMethodprimo::codecs::H265Levelprimo::codecs::H265Profileprimo::codecs::H265Tierprimo::codecs::InterpolationMethodprimo::codecs::MediaSampleFlagsprimo::codecs::MediaTypeprimo::codecs::Metaprimo::codecs::MetaPictureTypeprimo::codecs::MimeTypeprimo::codecs::OpusApplicationprimo::codecs::PcmFlagsprimo::codecs::PictureTypeprimo::codecs::ScanTypeprimo::codecs::StereoModeprimo::codecs::StreamSubTypeprimo::codecs::StreamTypeprimo::errorprimo::error::ErrorFacility
Source¶
1#ifndef ___PRIMO_CODECS_AV_H___
2#define ___PRIMO_CODECS_AV_H___
3
4/** @file */
5
6#include <primo/platform/reference.h>
7#include <primo/platform/error.h>
8
9#undef min
10
11namespace primo
12{
13 /**
14 Shared namespace for error definitions
15 */
16 namespace error
17 {
18 /**
19 Common error facilities
20 */
21 namespace ErrorFacility
22 {
23 /**
24 Common errors for encoders, decoders, muxers, demuxers and other A/V components.
25
26 @see primo::codecs::CodecError::Enum
27 */
28 const int32_t Codec = 9;
29 }
30 }
31
32 /**
33 Common audio/video types and interfaces
34 */
35 namespace codecs {
36
37 // TODO: Add images from https://en.wikipedia.org/wiki/Alpha_compositing
38 /**
39 Defines the way a foreground image will be combined with background video
40 */
41 namespace AlphaCompositingMode
42 {
43 enum Enum
44 {
45 /**
46 Foreground over Background - in effect, normal painting operation.
47
48 @remarks
49 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
50
51 Rrgb = (Fa * Frgb) + (1 - Fa ) * (Ba * Brgb)
52
53 Normally, alpha blending implies a background alpha of 1.0 (Ba = 1.0), so the compositing result Rrgb becomes:
54
55 Rrgb = (Fa * Frgb) + (1 - Fa) * Brgb
56
57 Fa and Ba are alpha density value with range from 0.0 to 1.0
58 */
59 Over = 1,
60
61 /**
62 Foreground in Background - the alpha compositing equivalent of clipping / itersection.
63
64 @remarks
65 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
66
67 Rrgb = (Fa * Frgb) * Ba
68
69 Fa and Ba are alpha density value with range from 0.0 to 1.0
70 */
71 In = 2,
72
73 /**
74 Foreground outside Background.
75
76 @remarks
77 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
78
79 Rrgb = (Fa * Frgb) * (1 - Ba)
80
81 Fa and Ba are alpha density value with range from 0.0 to 1.0
82 */
83 Out = 3,
84
85 /**
86 Foreground atop Background.
87
88 @remarks
89 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
90
91 Rrgb = (Fa * Frgb) * Ba + (1 - Fa) * (Ba * Brgb)
92
93 Fa and Ba are alpha density value with range from 0.0 to 1.0
94 */
95 Atop = 4,
96
97 /**
98 Foreground xor Background.
99
100 @remarks
101 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
102
103 Rrgb = (Fa * Frgb) * (1 - Ba) + (1 - Fa) * (Ba * Brgb)
104
105 Fa and Ba are alpha density value with range from 0.0 to 1.0
106 */
107 Xor = 5,
108
109 /**
110 Foreground plus Background.
111
112 @remarks
113 If Fa is foreground alpha, Frgb is foreground RGB, Ba is background alpha, Brgb is background RGB, then Rrgb is the compositing result:
114
115 Rrgb = (Fa * Frgb) + (Ba * Brgb)
116
117 Fa and Ba are alpha density value with range from 0.0 to 1.0
118 */
119 Plus = 6,
120 };
121 }
122
123 /**
124 Common errors for encoders, decoders, muxers, demuxers and other A/V components.
125
126 @see primo::ErrorFacility::Codec
127 */
128 namespace CodecError
129 {
130 enum Enum
131 {
132 /*
133 Success.
134 */
135 Success = 0,
136
137 /**
138 Failed to initialize or open codec
139 */
140 Init = 1,
141
142 /**
143 Codec configuration data is required, but is missing.
144 This data is part of a container format and is stored separately
145 from the audio/video stream.
146 It is essential for decoding an elementary stream stored in the container.
147 */
148 NoConfigData = 2,
149
150 /**
151 No output has been generated (insufficient input data).
152 This is a non-fatal error.
153 The component may recover after it receives more valid data.
154 */
155 NoOutput = 3,
156
157 /**
158 The output buffer is not big enough for the generated output data.
159 */
160 OutputBufferNotEnough = 4,
161
162 /**
163 Unsupported format or operation.
164 */
165 Unsupported = 5,
166
167 /**
168 The operation failed for unknown reason.
169 */
170 Failed = 6,
171
172 /**
173 The operation cannot be completed because the component is not initialized.
174 */
175 NotInitialized = 7,
176
177 /**
178 One or more of the input parameters are <b>NULL</b>
179 but are expected to be valid pointers.
180 */
181 NullPointer = 8,
182
183 /**
184 End of stream; no more data.
185 */
186 EOS = 9,
187
188 /**
189 Failed to allocate memory.
190 */
191 Alloc = 10,
192
193 /**
194 Invalid bitstream.
195 */
196 InvalidStream = 11,
197
198 /**
199 The operation is not implemented yet.
200 */
201 NotImplemented = 12,
202
203 /**
204 At least one of the input parameters has an invalid value for the specified operation.
205 Check ErrorInfo::hint() for details.
206 */
207 InvalidParams = 13,
208
209 /**
210 The operation is not allowed.
211 Check ErrorInfo::hint() for more details.
212 */
213 InvalidOperation = 14,
214
215 /**
216 A required library/dependency is not present.
217 Check ErrorInfo::hint() for more details.
218 */
219 MissingDependency = 15,
220
221 /**
222 Could not open a user stream (primo::Stream).
223 */
224 StreamOpen = 16,
225
226 /**
227 Could not read from a user stream (primo::Stream).
228 */
229 StreamRead = 17,
230
231 /**
232 Could not write to a user stream (primo::Stream).
233 */
234 StreamWrite = 18,
235
236 /**
237 Could not seek in a user stream (primo::Stream).
238 */
239 StreamSeek = 19,
240
241 /**
242 One of the input/output buffers is full and cannot accept more data.
243 */
244 BufferFull = 20,
245
246 /**
247 Intel QuickSync Video hardware not found.
248 */
249 MissingHardwareIntelQuickSync = 21,
250
251 /**
252 AMD VCE hardware not found.
253 */
254 MissingHardwareAmdVce = 22,
255
256 /**
257 NVIDIA NVENC hardware not found.
258 */
259 MissingHardwareNvidiaNVENC = 23,
260
261 /**
262 Error while decoding due to unsupported decoding settings.
263 @verison 3.3
264 */
265 Decoding = 24,
266
267 /**
268 Error while encoding due to unsupported encoding settings.
269 @verison 3.3
270 */
271 Encoding = 25,
272 };
273 }
274
275
276 /**
277 Defines constants for various LPCM properties.
278
279 The constants are expressed as bit flags and can be combined together.
280
281 @see AudioStreamInfo::flags
282 */
283 namespace PcmFlags
284 {
285 /**
286 PcmFlags::Enum
287 */
288 enum Enum
289 {
290 /**
291 No flag is set.
292 */
293 None = 0,
294
295 /**
296 The audio sample should be interpreted as an unsigned integral value.
297 The sample resolution (8-bit, 16-bit, etc.) is a separate LPCM property and is not expressed with PcmFlags.
298 This flag is irrelevant when the Float flag is set.
299 */
300 Unsigned = 0x1,
301
302 /**
303 The audio sample should be interpreted as a floating point value.
304 The sample resolution (32-bit, 64-bit, etc.) is a separate LCPM property and is not expressed with PcmFlags.
305 */
306 Float = 0x2,
307
308 /**
309 The sample value is stored in a big-endian format.
310 When this flag is not set the sample format is little-endian.
311 */
312 BigEndian = 0x4,
313
314 /**
315 When this flag is set audio samples from different channels are not interleaved.
316 All samples from channel 0 are first in memory. They are followed by all samples from channel 1 and so on
317 for all channels.
318
319 When this flag is not set the samples are interleaved. The first samples from all channels are first in memory.
320 They are followed by the second samples from all channels and so on until the last sample in time.
321 */
322 NonInterleaved = 0x8,
323 };
324 }
325
326 /**
327 Defines the speaker location of one or more audio channels.
328
329 These channel constants are expressed as bit flags and can be combined together.
330 A number of common speaker layouts are defined for convenience.
331 */
332 namespace AudioChannelFlags
333 {
334 /**
335 AudioChannelFlags::Enum
336 */
337 enum Enum
338 {
339 /** No flag is set. */
340 None = 0x0,
341
342 /** Left */
343 Left = 0x1,
344
345 /** Right */
346 Right = 0x2,
347
348 /** Center */
349 Center = 0x4,
350
351 /** Low-frequency effect. Subwoofer. */
352 LFE = 0x8,
353
354 /** Back-left. Also known as Left Surround. */
355 BackLeft = 0x10,
356
357 /** Back-right. Also known as Right Surround. */
358 BackRight = 0x20,
359
360 /** Front, left of center. */
361 LeftCenter = 0x40,
362
363 /** Front, right of center. */
364 RightCenter = 0x80,
365
366 /** Back-center. Also known as Center Surround. */
367 BackCenter = 0x100,
368
369 /** Side-left. Also known as Left Surround Direct. */
370 SideLeft = 0x200,
371
372 /** Side-right. Also known as Right Surround Direct. */
373 SideRight = 0x400,
374
375 /** Top-center. Also known as Top Center Surround. */
376 TopCenter = 0x800,
377
378 /** Top-front-left. Also known as Vertical Height Left. */
379 TopFrontLeft = 0x1000,
380
381 /** Top-front-center. Also known as Vertical Height Center. */
382 TopFrontCenter = 0x2000,
383
384 /** Top-front-right. Also known as Vertical Height Right. */
385 TopFrontRight = 0x4000,
386
387 /** Top-back-left */
388 TopBackLeft = 0x8000,
389
390 /** Top-back-center */
391 TopBackCenter = 0x10000,
392
393 /** Top-back-right */
394 TopBackRight = 0x20000,
395
396
397 /* Standard layouts */
398
399 /** Mono */
400 LayoutMono = Center,
401
402 /** Stereo */
403 LayoutStereo = Left | Right,
404
405 /** Standard 3-channel layout (2.1) */
406 Layout2p1 = Left | Right | LFE,
407
408 /** Standard 4-channel layout. Surround. */
409 LayoutSurround = Left | Right | Center | BackCenter,
410
411 /** Alternative 4-channel layout. */
412 LayoutQuad = Left | Right | BackLeft | BackRight,
413
414 /** Standard 5-channel layout (4.1) */
415 Layout4p1 = Left | Right | LFE | BackLeft | BackRight,
416
417 /** Standard 6-channel layout (5.1) */
418 Layout5p1 = Left | Right | Center | LFE | BackLeft | BackRight,
419
420 /** Standard 8-channel layout (7.1). Surround. */
421 Layout7p1Surround = Left | Right | Center | LFE | BackLeft | BackRight | SideLeft | SideRight,
422
423 /** Alternative 6-channel surround (5.1). Surround. */
424 Layout5p1Surround = Left | Right | Center | LFE | SideLeft | SideRight,
425
426 /** Alternative 8-channel layout (7.1) */
427 Layout7p1 = Left | Right | Center | LFE | BackLeft | BackRight | LeftCenter | RightCenter,
428
429 };
430 }
431
432 /**
433 Defines the bitrate mode of the audio/video stream.
434 */
435 namespace BitrateMode
436 {
437 /**
438 BitrateMode::Enum
439 */
440 enum Enum
441 {
442 /**
443 The bitrate mode is not specified or unknown.
444 */
445 Unknown = 0,
446
447 /**
448 Constant bitrate.
449
450 For uncompressed audio/video with constant bitrate the quality is also constant.
451 For compressed audio/video with constant bitrate the quality may be constant or variable.
452 */
453 CBR = 1,
454
455 /**
456 Variable bitrate - quality oriented. Constant quality (more or less).
457 */
458 VBR = 2,
459
460 /**
461 Average bitrate.
462
463 Guarantees a predictable audio/video size similar to CBR.
464 The bitrate changes to achieve the best quality within the available bitrate capacity.
465 */
466 ABR = 3,
467 };
468 }
469
470
471 /**
472 Defines constants for various color formats.
473
474 A color format is combination of color space, color depth, chroma subsampling, component layout and packing.
475 */
476 namespace ColorFormat
477 {
478 /**
479 ColorFormat::Enum
480 */
481 enum Enum
482 {
483 /** The color format is not specified or unknown. */
484 Unknown = 0,
485
486 /** Planar Y, V, U (4:2:0) (note V,U order!) */
487 YV12 = 1,
488
489 /** Planar Y, merged U->V (4:2:0) */
490 NV12 = 2,
491
492 /** Composite Y->U->Y->V (4:2:2) */
493 YUY2 = 3,
494
495 /** Composite U->Y->V->Y (4:2:2) */
496 UYVY = 4,
497
498 /** Planar Y, U, V (4:1:1) */
499 YUV411 = 5,
500
501 /** Planar Y, U, V (4:2:0) */
502 YUV420 = 6,
503
504 /** Planar Y, U, V (4:2:2) */
505 YUV422 = 7,
506
507 /** Planar Y, U, V (4:4:4) */
508 YUV444 = 8,
509
510 /** Composite Y, U, V (4:1:1) */
511 Y411 = 9,
512
513 /** Composite Y, U, V (4:1:1) */
514 Y41P = 10,
515
516 /** Composite B->G->R */
517 BGR32 = 11,
518
519 /** Composite B->G->R */
520 BGR24 = 12,
521
522 /** Composite B->G->R, 5 bit per B & R, 6 bit per G */
523 BGR565 = 13,
524
525 /** Composite B->G->R->A, 5 bit per component, 1 bit per A */
526 BGR555 = 14,
527
528 /** Composite B->G->R->A, 4 bit per component */
529 BGR444 = 15,
530
531 /** Luminance component only. */
532 GRAY = 16,
533
534 /** Planar Y, U, V, Alpha */
535 YUV420A = 17,
536
537 /** Planar Y, U, V, Alpha */
538 YUV422A = 18,
539
540 /** Planar Y, U, V, Alpha */
541 YUV444A = 19,
542
543 /** Planar Y, V, U
544 The vertical subsampling interval is 4. The horizontal subsampling interval is also 4
545 This means that a single V and a single U sample are taken for each square block of 16 image pixels.
546 Effectively this averages 9 bits per pixel (16 pixels => 16Y + 1V + 1U => 144bits => 9bits/pixel)
547 */
548 YVU9 = 20,
549
550 /** Composite B->G->R->A */
551 BGRA32 = 21,
552 };
553 }
554
555 /**
556 Defines major audio and video stream types, and file formats (a.k.a. containers).
557 */
558 namespace StreamType
559 {
560 /**
561 StreamType::Enum
562 */
563 enum Enum
564 {
565 /**
566 The stream type is not defined or is unknown.
567 */
568 Unknown = 0,
569
570 /**
571 This constant marks the start of audio elementary streams.
572 It is not a valid stream type on its own.
573 */
574 BEGIN_AUDIO = 0x1000,
575
576 /** Audio encoded using pulse code modulation (PCM) with linear quantization. */
577 LPCM = 0x1001,
578
579 /** G.711 A-law PCM. */
580 ALAW_PCM = 0x1002,
581
582 /** G.711 Mu-law PCM. */
583 MULAW_PCM = 0x1003,
584
585 /**
586 LPCM with specific sample packing for Video-DVD.
587 */
588 VIDEO_DVD_PCM = 0x1004,
589
590
591 /** Dolby Digital Audio (a.k.a. AC-3). AC-3 is defined in ATSC A/52-A and A/52-B. */
592 AC3 = 0x1005,
593
594 /** DTS (Digital Theater Systems) Coherent Acoustics codec, transportable through S/PDIF and used on DVDs, CD-DAs, LDs, and in wave files. */
595 DTS = 0x1006,
596
597 /**
598 MPEG-1 or MPEG-2 Audio, Layer I, II and III.
599 */
600 MPEG_Audio = 0x1007,
601
602 /**
603 Vorbis Audio Codec. This is an open standard audio codec developed by the Xiph.Org Foundation.
604 */
605 Vorbis = 0x1008,
606
607 /**
608 Advanced Audio Coding.
609
610 Initially it was defined in Part 7 of the MPEG-2 standard (known formally as ISO/IEC 13818-7) which is now obsolete.
611
612 Currently it is defined in Part 3 of the MPEG-4 standard (known formally as ISO/IEC 14496-3).
613 */
614 AAC = 0x1009,
615
616 /** Adaptive Multi-Rate audio (Narrow Band). */
617 AMRNB = 0x100A,
618
619 /** Adaptive Multi-Rate audio (Wide Band). */
620 AMRWB = 0x100B,
621
622 /** G.726 ITU-T ADPCM */
623 G726_ADPCM = 0x100C,
624
625 /** Microsoft Windows Media Audio. */
626 WMA = 0x100D,
627
628 /** Microsoft Windows Media Audio Professional. */
629 WMA_Professional = 0x100E,
630
631 /** Microsoft Windows Media Audio Lossless. */
632 WMA_Lossless = 0x100F,
633
634 /** Opus Audio Codec. This is an open, royalty-free audio codec developed by the Xiph.Org Foundation and standardized by IETF. */
635 Opus = 0x1010,
636
637 /**
638 This constant marks the end of audio elementary streams.
639 It is not a valid stream type on its own.
640 */
641 END_AUDIO = 0x1FFF,
642
643
644 /**
645 This constant marks the start of video elementary streams.
646 It is not a valid stream type on its own.
647 */
648 BEGIN_VIDEO = 0x2000,
649
650
651 /** Uncompressed video stream. */
652 UncompressedVideo = 0x2001,
653
654 /** MPEG-1 Video is defined in Part 2 of the MPEG-1 standard (known formally as ISO/IEC-11172-2). */
655 MPEG1_Video = 0x2002,
656
657 /** MPEG-2 Video is defined in Part 2 of the MPEG-2 standard (known formally as ISO/IEC 13818-2 and as ITU-T H.262). */
658 MPEG2_Video = 0x2003,
659
660 /** MPEG-4 Video is defined in Part 2 of the MPEG-4 standard (known formally as ISO/IEC 14496-2). */
661 MPEG4_Video = 0x2004,
662
663 /** H.261 Video is defined in the ITU-T H.261 standard. */
664 H261 = 0x2005,
665
666 /** H.263 Video is defined in the ITU-T H.263 standard. */
667 H263 = 0x2006,
668
669 /**
670 H.264 Video (also known as MPEG-4 AVC / Advanced Video Codec).
671
672 Defined in Part 10 of the MPEG-4 standard (known formally as ISO/IEC 14496-10 and as ITU-T H.264).
673
674 The actual bitstream format is determined by the stream sub-type:
675
676 <p>
677 [StreamSubType::AVC_Annex_B](@ref primo::codecs::StreamSubType::AVC_Annex_B)
678
679 H.264 Bitstream WITH start codes
680
681 H.264 bitstreams are transmitted in this format over the air, or contained in MPEG-2 program or transport streams.
682 The H.264 bitstream is formatted as described in Annex B of ITU-T Rec. H.264. According to this specification, the bitstream consists of a sequence of NALUs (Network Abstraction Layer Units).
683 Each NALU is prefixed with a start code equal to 0x000001 or 0x00000001.
684
685 <p>
686 [StreamSubType::AVC1](@ref primo::codecs::StreamSubType::AVC1)
687
688 H.264 Bitstream WITHOUT start codes
689
690 H.264 bitstreams are stored in the MP4 container in this format. Instead of start codes, each NALU (Network Abstraction Layer Units) is prefixed by a length field, which gives the length of the NALU in bytes.
691 The size of the length field can vary, but is typically 1, 2, or 4 bytes.
692 */
693 H264 = 0x2007,
694
695 /**
696 Alias. Same as [StreamType::H264](@ref primo::codecs::StreamType::H264).
697 */
698 AVC = H264,
699
700 /** Microsoft Windows Media Video. */
701 WMV = 0x2008,
702
703 /** Motion JPEG (M-JPEG). */
704 MJPEG = 0x2009,
705
706 /** VC-1 Video is defined in the SMPTE 421M-2006 standard. */
707 VC1 = 0x200A,
708
709 /** Advanced Video Standard (Chinese national standard) */
710 AVS = 0x200B,
711
712 /**
713 VP8 is an open video codec released by Google, originally created by On2 Technologies. VP8 is part of the WebM format.
714 */
715 VP8 = 0x200C,
716
717 /**
718 Theora Video Codec. This is an open standard video codec developed by the Xiph.Org Foundation.
719 */
720 Theora = 0x200D,
721
722 /**
723 H.265 Video (also known as MPEG-H HEVC / High Efficiency Video Codec )
724
725 Defined in Part 2 of the MPEG-H standard (known formally as ISO/IEC 23008-2 and as ITU-T H.265).
726 */
727 H265 = 0x200E,
728
729 /**
730 Alias. Same as [StreamType::H265](@ref primo::codecs::StreamType::H265).
731 */
732 HEVC = H265,
733
734 /**
735 VP9 is an open video codec released by Google as a successor to VP8. VP9 is part of the WebM format.
736 @verison 3.3
737 */
738 VP9 = 0x200F,
739
740 /**
741 AV1 is an open, royalty-free video coding format designed for video transmissions over the Internet.
742 @verison 3.3
743 */
744 AV1 = 0x2010,
745
746 /**
747 AV2 is the successor to the AV1 video coding format. It is being developed by the Alliance for Open Media (AOMedia).
748 @verison 3.3
749 */
750 AV2 = 0x2011,
751
752 /**
753 This constant marks the end of the elementary video streams.
754 It is not a valid stream type on its own.
755 */
756 END_VIDEO = 0x2FFF,
757
758 /**
759 This constant marks the start of audio/video containers.
760 It is not a valid stream type on its own.
761 */
762 BEGIN_CONTAINER = 0x3000,
763
764 /** Audio Video Interleave (AVI) multimedia container format. */
765 AVI = 0x3001,
766
767 /** MPEG-4 multimedia container format specified in Part 14 of the MPEG-4 standard (formally ISO/IEC 14496-14:2003). */
768 MP4 = 0x3002,
769
770 /** Advanced Systems Format (formerly Advanced Streaming Format, Active Streaming Format) (ASF). */
771 ASF = 0x3003,
772
773 /** MPEG program stream. */
774 MPEG_PS = 0x3004,
775
776 /** MPEG transport stream. */
777 MPEG_TS = 0x3005,
778
779 /** MPEG Packetized Elementary Stream (PES). */
780 MPEG_PES = 0x3006,
781
782 /** Waveform Audio file format (WAV, WAVE). */
783 WAVE = 0x3007,
784
785 /**
786 Adobe Flash Video container format (FLV).
787 Not to be confused with F4V which is a newer Flash Video container format based on ISO/IEC 14496-12 (MPEG-4 Part 12).
788 */
789 FLV = 0x3008,
790
791 /**
792 Open standard container format developed by the Xiph.Org Foundation.
793 */
794 OGG = 0x3009,
795
796 /**
797 Open standard container format based on a profile of Matroska.
798 */
799 WebM = 0x300A,
800
801 /**
802 Duck Keyframe / Interframe Video Format. This is a simple (video only) container format that transports raw VP8, VP9, AV1, and AV2 video.
803 @version 3.3
804 */
805 IVF = 0x300B,
806
807 /**
808 This constant marks the end of audio/video containers.
809 It is not a valid stream type on its own.
810 */
811 END_CONTAINER = 0x3FFF,
812
813 /**
814 This constant marks the start of image types.
815 It is not an image type on its own.
816 */
817 BEGIN_IMAGE = 0x4000,
818
819 /**
820 BMP image.
821 */
822 BMP = 0x4001,
823
824 /**
825 PNG image.
826 */
827 PNG = 0x4002,
828
829 /**
830 JPEG image.
831 */
832 JPEG = 0x4003,
833
834 /**
835 TIFF image.
836 */
837 TIFF = 0x4004,
838
839 /**
840 GIF image.
841 */
842 GIF = 0x4005,
843
844 /**
845 This constant marks the end of image types.
846 It is not an image type on its own.
847 */
848 END_IMAGE = 0x4FFF,
849
850 /**
851 This constant marks the start of various data types.
852 */
853 BEGIN_DATA = 0x5000,
854
855 /**
856 Teletext data
857 */
858 Teletext = 0x5001,
859
860 /**
861 MPEG Transport Stream Program Specific Information
862 */
863 MPEG_PSI_PACKETS = 0x5002,
864
865 /**
866 MPEG transport stream packets.
867 This is not a complete transport stream but rather a subset of the original transport stream.
868 */
869 MPEG_TS_PACKETS = 0x5003,
870
871 /**
872 This constant marks the end of various data types.
873 */
874 END_DATA = 0x5FFF,
875 };
876 }
877
878 /**
879 Defines audio and video stream subtypes.
880 */
881 namespace StreamSubType
882 {
883 /**
884 StreamSubType::Enum
885 */
886 enum Enum
887 {
888 /** The stream subtype is unknown. */
889 Unknown = 0,
890
891 /** No stream subtype is defined. */
892 None = 0xFFFF,
893
894 /**
895 Audio Data Transport Stream: AAC data in frames, similar to mp3. Somewhat compliant.
896 Defined in Part 7 of the MPEG-2 standard (known formally as ISO/IEC 13818-7).
897 */
898 AAC_ADTS = 1,
899
900 /**
901 Audio Data Interchange Format: AAC data with a single header. Worst compliance.
902 Defined in Part 7 of the MPEG-2 standard (known formally as ISO/IEC 13818-7).
903 */
904 AAC_ADIF = 2,
905
906 /** AAC data packed in MPEG-4 container (MP4). Best compliance. */
907 AAC_MP4 = 3,
908
909 /**
910 H.264/AVC bitstream without start codes.
911
912 This is how the bitstream is stored in a MPEG-4 container (MP4).
913 Instead of start codes, each NALU is prefixed by a length field, which gives the length of the NALU in bytes.
914 The size of the length field can vary, but is typically 1, 2, or 4 bytes.
915
916 Defined in ISO 14496-15.
917 */
918 AVCC = 4,
919
920 /**
921 Alias. Same as [StreamSubType::AVCC](@ref primo::codecs::StreamSubType::AVCC).
922 */
923 AVC1 = AVCC,
924
925 /** MPEG2 transport stream with valid packet time stamps. */
926 MPEG_TS_BDAV = 5,
927
928 /**
929 MPEG-1 Audio Layer I is commonly abbreviated to MP1. MPEG-1 Layer I is defined in ISO/IEC 11172-3.
930
931 MPEG-2 Layer I is defined in the MPEG-2 Part 3 standard (known formally as ISO/IEC 13818-3).
932 */
933 MPEG_Audio_Layer1 = 6,
934
935 /**
936 MPEG-1 Audio Layer II is commonly abbreviated to MP2. MP2 is a dominant standard for audio broadcasting.
937 MPEG-1 Layer II is defined in ISO/IEC 11172-3.
938
939 MPEG-2 Layer II is defined in the MPEG-2 Part 3 standard (known formally as ISO/IEC 13818-3).
940 */
941 MPEG_Audio_Layer2 = 7,
942
943 /**
944 MPEG-1 Audio Layer III is commonly abbreviated to MP3. MPEG-1 Layer III is defined in ISO/IEC 11172-3.
945
946 MPEG-2 Layer III is defined in the MPEG-2 Part 3 standard (known formally as ISO/IEC 13818-3).
947 */
948 MPEG_Audio_Layer3 = 8,
949
950 /**
951 G.726 stream packed according to RFC 3551.
952 This type of packetization is used in RTP.
953 See: https://datatracker.ietf.org/doc/html/rfc3551#section-4.5.4
954 */
955 G726_RFC3551 = 9,
956
957 /**
958 Alias. Same as [StreamSubType::G726_RFC3551](@ref primo::codecs::StreamSubType::G726_RFC3551).
959 */
960 G726_PACKED_RFC3551 = G726_RFC3551,
961
962 /**
963 G.726 stream packed according to ITU-T I.366.2 (AAL type 2).
964 This type of packetization is tyically used in Wave files.
965 See: ITU-T Recommendation I.366.2 Annex E - Encoding format for audio algorithm G.726.
966 */
967 G726_AAL2 = 10,
968
969 /**
970 Alias. Same as [StreamSubType::G726_AAL2](@ref primo::codecs::StreamSubType::G726_AAL2).
971 */
972 G726_PACKED_AAL2 = G726_AAL2,
973
974 /**
975 MPEG-1 Program Stream as specified in MPEG-1 Part 1 (ISO/IEC 11172-1).
976 This stream subtype can be used only with the [MPEG_PS](@ref primo::codecs::StreamType::MPEG_PS) stream type.
977 */
978 MPEG1_System = 11,
979
980 /**
981 MPEG-2 Program Stream as specified in MPEG-2 Part 1 (ISO/IEC 13818-1).
982 This stream subtype can be used only with the [MPEG_PS](@ref primo::codecs::StreamType::MPEG_PS) stream type.
983 */
984 MPEG2_System = 12,
985
986 /**
987 H.264 bitstream with start codes.
988
989 H.264 bitstreams are transmitted in this format over the air, or contained in MPEG-2 program or transport streams.
990 The H.264 bitstream is formatted as described in Annex B of ITU-T Rec. H.264. According to this specification,
991 the bitstream consists of a sequence of NALUs (Network Abstraction Layer Units).
992 Each NALU is prefixed with a start code equal to 0x000001 or 0x00000001.
993 */
994 AVC_Annex_B = 13,
995
996 /**
997 Raw AAC data format: AAC data is stored without headers.
998 */
999 AAC_RAW = 14,
1000
1001 // TBR:
1002 // Python:
1003 // Plus:
1004 /**
1005 H.265/HEVC bitstream with start codes.
1006
1007 H.265 bitstreams are transmitted in this format over the air, or contained in MPEG-2 program or transport streams.
1008 The H.265 bitstream is formatted as described in Annex B of ITU-T Rec. H.265. According to this specification,
1009 the bitstream consists of a sequence of NALUs (Network Abstraction Layer Units).
1010 Each NALU is prefixed with a start code equal to 0x000001 or 0x00000001.
1011 */
1012 HEVC_Annex_B = 15,
1013
1014 // TBR:
1015 // Python:
1016 // Plus:
1017 /**
1018 H.265/HEVC bitstream without start codes.
1019
1020 This is how the bitstream is stored in a MPEG-4 container (MP4).
1021 Instead of start codes, each NALU is prefixed by a length field, which gives the length of the NALU in bytes.
1022 The size of the length field can vary, but is typically 1, 2, or 4 bytes.
1023
1024 Defined in ISO 14496-15.
1025 */
1026 HVCC = 16,
1027
1028 // TBR:
1029 // Python:
1030 // Plus:
1031 /** Alias. Same as [StreamSubType::HVCC](@ref primo::codecs::StreamSubType::HVCC). */
1032 HVC1 = HVCC,
1033 };
1034 }
1035
1036 /**
1037 Defines video interlace/scan types.
1038 */
1039 namespace ScanType
1040 {
1041 /**
1042 ScanType::Enum
1043 */
1044 enum Enum
1045 {
1046 /** The interlace/scan type is not specified or not known. */
1047 Unknown = 0,
1048
1049 /** Progressive (non-interlaced) video. */
1050 Progressive = 1,
1051
1052 /** Interlaced video, where the dominant (first in time) field is the top field. */
1053 TopFieldFirst = 2,
1054
1055 /** Interlaced video, where the dominant (first in time) field is the bottom field. */
1056 BottomFieldFirst = 3,
1057 };
1058 }
1059
1060 /**
1061 Defines video deinterlacing methods
1062 */
1063 namespace DeinterlacingMethod
1064 {
1065 /**
1066 DeinterlacingMethod::Enum
1067 */
1068 enum Enum
1069 {
1070 /**
1071 No deinterlacing is performed.
1072 This can be used to prevent automatic deinterlacing if it's not desired.
1073 */
1074 NoDeinterlacing = 0,
1075
1076 /**
1077 Line doubling.
1078 */
1079 Duplicate = 1,
1080
1081 /**
1082 Motion adaptive deinterlacing
1083 */
1084 Blend = 2,
1085
1086 /**
1087 Calculates the median of consecutive fields
1088 */
1089 Median = 3,
1090
1091 /**
1092 Uses an edge detection filter.
1093 */
1094 EdgeDetect = 4,
1095
1096 /**
1097 Calculates the median of consecutive fields using a threshold.
1098 */
1099 MedianThreshold = 5,
1100
1101 /**
1102 Content adaptive vertical temporal (CAVT) filtering
1103 */
1104 CAVT = 6
1105 };
1106 }
1107
1108 /**
1109 Defines methods for sample interpolation
1110 */
1111 namespace InterpolationMethod
1112 {
1113 /**
1114 InterpolationMethod::Enum
1115 */
1116 enum Enum
1117 {
1118 /**
1119 The interpolation method is unknown or not set.
1120 */
1121 Unknown = 0,
1122
1123 /**
1124 Nearest neighbor interpolation
1125 */
1126 NearestNeighbor = 1,
1127
1128 /**
1129 Linear interpolation
1130 */
1131 Linear = 2,
1132
1133 /**
1134 Cubic convolution interpolation
1135 */
1136 Cubic = 4,
1137
1138 /**
1139 Supersampling interpolation.
1140 */
1141 Super = 8,
1142
1143 /**
1144 Interpolation by 3-lobed Lanczos-windowed sinc function
1145 */
1146 Lanczos = 16
1147 };
1148 }
1149
1150 /**
1151 Defines H.264/AVC profiles
1152
1153 @note The constants follow the H.264 spec for the element "profile_idc"
1154 */
1155 namespace H264Profile
1156 {
1157 /**
1158 H264Profile::Enum
1159 */
1160 enum Enum
1161 {
1162 /**
1163 None/Auto
1164 */
1165 None = 0,
1166
1167 /**
1168 Baseline profile
1169 */
1170 Baseline = 66,
1171
1172 /**
1173 Main profile
1174 */
1175 Main = 77,
1176
1177 /**
1178 High
1179 */
1180 High = 100,
1181
1182 /*
1183 High 10
1184 */
1185 High10 = 110,
1186
1187 /*
1188 High 4:2:2
1189 */
1190 High422 = 122,
1191
1192 /*
1193 High 4:4:4
1194 */
1195 High444 = 144
1196 };
1197 }
1198
1199 /**
1200 Defines H.264/AVC entropy coding modes
1201
1202 @note The constants follow the H.264 spec for the element "entropy_coding_mode_flag"
1203 */
1204 namespace H264EntropyCodingMode
1205 {
1206 /**
1207 H264EntropyCodingMode::Enum
1208 */
1209 enum Enum
1210 {
1211 /**
1212 Context-Adaptive Variable-Length Coding (CAVLC)
1213 */
1214 CAVLC = 0,
1215
1216 /**
1217 Context-Adaptive Binary Arithmetic Coding (CABAC)
1218 */
1219 CABAC = 1,
1220 };
1221 }
1222
1223 /**
1224 Defines H.264/AVC deblocking filter mode.
1225
1226 @note The constants follow the H.264 spec for the element "disable_deblocking_filter_idc"
1227 */
1228 namespace H264DeblockingFilter
1229 {
1230 /**
1231 H264DeblockingFilter::Enum
1232 */
1233 enum Enum
1234 {
1235 /**
1236 Deblocking filter is applied on all luma and chroma block edges of the slice.
1237 */
1238 All = 0,
1239
1240 /**
1241 Deblocking filter is disabled for all block edges of the slice.
1242 */
1243 Off = 1,
1244
1245 /**
1246 Deblocking filter is applied on all luma and chroma block edges of the slice
1247 with exception of the block edges that coincide with slice boundaries.
1248 */
1249 InSlice = 2,
1250 };
1251 }
1252
1253 /**
1254 Defines H.264/AVC direct predition mode.
1255
1256 @note The constants follow the H.264 spec for the element "direct_spatial_mv_pred_flag"
1257 */
1258 namespace H264DirectPredMode
1259 {
1260 /*
1261 H264DirectPredMode::Enum
1262 */
1263 enum Enum
1264 {
1265 /**
1266 Temporal direct mode prediction
1267 */
1268 Temporal = 0,
1269
1270 /**
1271 Spatial direct mode prediction
1272 */
1273 Spatial = 1,
1274 };
1275 }
1276
1277 /**
1278 Defines the block sizes for which motion estimation should be done.
1279
1280 @note Used when encoding H.264/AVC.
1281 */
1282 namespace H264MeSplitMode
1283 {
1284 /*
1285 H264MeSplitMode::Enum
1286 */
1287 enum Enum
1288 {
1289 /**
1290 Analyze only 16x16 blocks for motion estimation
1291 */
1292 Only16x16 = 0,
1293
1294 /**
1295 Analyze all blocks down to 8x8 (16x16, 16x8, 8x16, 8x8)
1296 */
1297 DownTo8x8 = 1,
1298
1299 /**
1300 Analyze all blocks down to 4x4 (16x16, 16x8, 8x16, 8x8, 8x4, 4x8, 4x4).
1301
1302 @note This partitioning mode is very slow.
1303 */
1304 DownTo4x4 = 2,
1305 };
1306 }
1307
1308 /**
1309 Defines the motion estimation methods used when encoding H.264/AVC
1310 */
1311 namespace H264MeMethod
1312 {
1313 /**
1314 H264MeMethod::Enum
1315 */
1316 enum Enum
1317 {
1318 /**
1319 Full (slowest)
1320 */
1321 Full = 0,
1322
1323 /**
1324 TDL (Two Dimensional Logarithmic Search)
1325 */
1326 ClassicLog = 1,
1327
1328 /**
1329 Log
1330 */
1331 Log = 2,
1332
1333 /**
1334 EPZS (Enhanced Predictive Zonal Search)
1335 */
1336 EPZS = 3,
1337
1338 /**
1339 OSA (Full orthogonal)
1340 */
1341 FullOrthogonal = 4,
1342
1343 /**
1344 Log orthogonal
1345 */
1346 LogOrthogonal = 5,
1347
1348 /**
1349 UMH (Uneven Multi-Hexagon Search)
1350 */
1351 UMH = 8
1352 };
1353 }
1354
1355 /**
1356 Defines the picture coding type when encoding H.264/AVC
1357 */
1358 namespace H264PicCodingType
1359 {
1360 /**
1361 H264PicCodingType::Enum
1362 */
1363 enum Enum
1364 {
1365 /**
1366 Video pictures are coded as frames (progressive video)
1367 */
1368 Frames = 0,
1369
1370 /**
1371 Video pictures are coded as fields (interlaced video)
1372 */
1373 Fields = 1,
1374 };
1375 }
1376
1377 /**
1378 Defines methods for bitrate contorl when encoding H.264/AVC
1379 */
1380 namespace H264RateControlMethod
1381 {
1382 /**
1383 H264RateControlMethod
1384 */
1385 enum Enum
1386 {
1387 /**
1388 Average Bitrate.
1389 Ensures that the output stream achieves a predictable long-term average bitrate.
1390 */
1391 ABR = 2,
1392
1393 /**
1394 Constant Quantization.
1395 Encodes the video to a constant quantizer. The encoder uses the specified target quantizer, not a target bitrate.
1396 The quantizer is a measure for the amount of data loss: a higher quantizer means that more data will be lost,
1397 which results in a better compression, but also delivers worse visual quality.
1398 This method could be used when a certain level of quality is required and the final bitrate is not a concern.
1399 The bitrate is unpredictable in this mode.
1400 */
1401 ConstantQuant = 3,
1402 };
1403 }
1404
1405 /**
1406 Defines various media sample features.
1407
1408 These features are expressed as bit flags and can be combined together.
1409 */
1410 namespace MediaSampleFlags
1411 {
1412 /**
1413 MediaSampleFlags::Enum
1414 */
1415 enum Enum
1416 {
1417 /**
1418 No feature is specified.
1419 */
1420 None = 0x0,
1421
1422 /**
1423 The media sample / frame can be decoded on its own. It does not depend on previous or subsequent samples / frames.
1424 */
1425 KeyFrame = 0x1,
1426
1427 /*
1428 Beginning of stream
1429 */
1430 Bos = 0x2,
1431
1432 /*
1433 End of stream
1434 */
1435 Eos = 0x4,
1436 };
1437 }
1438
1439 /**
1440 Defines video picture types (I/P/B)
1441 */
1442 namespace PictureType
1443 {
1444 /**
1445 PictureType::Enum
1446 */
1447 enum Enum
1448 {
1449 /**
1450 Picture type is unknown or not specified.
1451 */
1452 None = 0,
1453
1454 /**
1455 I Picture
1456 */
1457 I = 1,
1458
1459 /**
1460 P Picture
1461 */
1462 P = 2,
1463
1464 /**
1465 B Picture
1466 */
1467 B = 3,
1468
1469 /**
1470 D Picture (MPEG-1 only)
1471 */
1472 D = 4,
1473 };
1474 }
1475
1476 /**
1477 Defines frame types for audio codecs, particularly for G.711 encoding.
1478 These types indicate the nature of the encoded frame, such as voice activity,
1479 silence, or errors, and are used to optimize transmission and decoding.
1480 Values are based on ITU-T G.711 standards and related codecs like G.729 Annex B for VAD.
1481
1482 @version 3.2
1483 */
1484 namespace FrameType
1485 {
1486 /**
1487 Enumeration of frame types used in audio encoding/decoding.
1488 Negative values indicate errors or unspecified states,
1489 while positive values represent specific frame categories.
1490 */
1491 enum Enum
1492 {
1493 /**
1494 Unknown frame type or frame type is not specified.
1495 Used when the frame type cannot be determined or is undefined.
1496 */
1497 None = 0,
1498
1499 /**
1500 G.711 bad frame: Indicates a corrupted or invalid frame that cannot be decoded.
1501 This may occur due to transmission errors or data loss.
1502 */
1503 G711BadFrame = 1,
1504
1505 /**
1506 G.711 untransmitted frame: Represents a frame that was not transmitted,
1507 often due to silence or inactivity in VAD-enabled modes.
1508 Equivalent to no data sent, saving bandwidth.
1509 */
1510 G711UntransmittedFrame = 2,
1511
1512 /**
1513 G.711 SID (Silence Insertion Descriptor) frame: A compact frame describing silence.
1514 Contains parameters (e.g., from G.729 Annex B VAD) to reconstruct background noise,
1515 used when voice activity is low to reduce bitrate.
1516 */
1517 G711SIDFrame = 3,
1518
1519 /**
1520 G.711 voice frame: A full voice/active frame encoded in G.711 A-law or μ-law.
1521 Contains compressed PCM data for speech or active audio segments.
1522 Frame size is 80 bytes (10ms at at sampling rate 8kHz, 8 bits per sample).
1523 */
1524 G711VoiceFrame = 5,
1525
1526 /**
1527 G.726 voice frame: A full voice/active frame encoded in G.726 Adaptive Differential Pulse Code Modulation (ADPCM).
1528 This is the only supported frame type for G.726 codec.
1529 Frame size varies based on the bitrate: 20, 30, 40 or 50 bytes for 16, 24, 32 or 40 kbps respectively (10ms at sampling rate 8kHz, 2, 3, 4, 5 bits per sample).
1530 Voice Activity Detection (VAD) and Packet Loss Concealment (PLC) are not supported for G.726.
1531 */
1532 G726VoiceFrame = 105
1533 };
1534 }
1535
1536 /**
1537 Defines H.265/HEVC profiles
1538 */
1539 namespace H265Profile
1540 {
1541 /**
1542 H265Profile::Enum
1543 */
1544 enum Enum
1545 {
1546 /**
1547 None/Auto
1548 */
1549 None = 0,
1550
1551 /**
1552 Main profile
1553 */
1554 Main = 1,
1555
1556 /**
1557 Main 10
1558 */
1559 Main10 = 2,
1560 };
1561 }
1562
1563 /**
1564 Defines H.265/HEVC levels
1565 */
1566 namespace H265Level
1567 {
1568 /**
1569 H265Level::Enum
1570 */
1571 enum Enum
1572 {
1573 /**
1574 None/Auto
1575 */
1576 None = 0,
1577 /**
1578 30
1579 */
1580 L1 = 30,
1581 /**
1582 60
1583 */
1584 L2 = 60,
1585 /**
1586 63
1587 */
1588 L21 = 63,
1589 /**
1590 90
1591 */
1592 L3 = 90,
1593 /**
1594 93
1595 */
1596 L31 = 93,
1597 /**
1598 120
1599 */
1600 L4 = 120,
1601 /**
1602 123
1603 */
1604 L41 = 123,
1605 /**
1606 150
1607 */
1608 L5 = 150,
1609 /**
1610 153
1611 */
1612 L51 = 153,
1613 /**
1614 156
1615 */
1616 L52 = 156,
1617 /**
1618 180
1619 */
1620 L6 = 180,
1621 /**
1622 183
1623 */
1624 L61 = 183,
1625 /**
1626 186
1627 */
1628 L62 = 186,
1629 };
1630 }
1631
1632 /**
1633 Defines H.265/HEVC tiers
1634 */
1635 namespace H265Tier
1636 {
1637 /**
1638 H265Tier::Enum
1639 */
1640 enum Enum
1641 {
1642 /**
1643 0
1644 */
1645 Main = 0,
1646 /**
1647 1
1648 */
1649 High = 1
1650 };
1651 }
1652
1653 // TBR:
1654 /**
1655 Defines stereo mode in MPEG Audio and AAC.
1656 */
1657 namespace StereoMode
1658 {
1659 /**
1660 StereoMode::Enum
1661 */
1662 enum Enum
1663 {
1664 /**
1665 None/LR mode is chosen by default.
1666 */
1667 None = 0,
1668
1669 /**
1670 If <b>MPEG/AAC</b> encoder is used with LR mode the encoding will be done using normal independent coding of left and right channels.
1671 */
1672 LR = 2,
1673
1674 /**
1675 If <b>AAC</b> encoder is used with mode MidSide the encoding will be done using Mid/Side coding technique.
1676 If <b>MPEG Audio</b> encoder is used with this mode:
1677 - Layers 1 and 2: the encoding will be done using normal independent coding of left and right channels(same as LR mode)
1678 - Layer 3: the encoding will be done using Mid/Side coding technique.
1679 */
1680 MidSide = 3,
1681
1682 /**
1683 If <b>AAC</b> encoder is used with mode Joint the encoding of every frame will be done with Mid/Side or Left-Right Stereo coding technique
1684 depending on the data present in the frame.
1685 If <b>MPEG Audio</b> encoder is used with this mode:
1686 - Layer 1: the encoding will be done using normal independent coding of left and right channels(same as LR mode).
1687 - Layer 2: the encoding will use Intensity coding technique when the bit rate is lower than 96Kb/s for 2 channel setup
1688 in combination with normal independent coding of left and right channels, otherwise will use only left and right coding.
1689 - Layer 3: the encoding of every frame will be done with Mid/Side or Left-Right Stereo coding technique
1690 depending on the data present in the frame.
1691 */
1692 Joint = 4,
1693 };
1694 }
1695
1696 /**
1697 Defines Opus codec application modes.
1698 */
1699 namespace OpusApplication
1700 {
1701 /**
1702 OpusApplication::Enum
1703 */
1704 enum Enum
1705 {
1706 /**
1707 Best for most VoIP / Video Conference applications
1708 where listening quality and intelligibility matter most
1709 */
1710 Voip = 2048,
1711 /**
1712 Best for broadcast/high-fidelity application
1713 where the decoded audio should be as close as possible to the input
1714 */
1715 Audio = 2049,
1716 /**
1717 Only use when lowest-achievable latency is what matters most.
1718 Voice-optimized modes cannot be used.
1719 */
1720 RestrictedLowDelay = 2051,
1721
1722 /** Force SILK encoding */
1723 RestrictedSilk = 2052,
1724
1725 /** Force CELT encoding */
1726 RestrictedCelt = 2053
1727 };
1728 }
1729
1730 /**
1731 A buffer for media data.
1732
1733 <b>MediaBuffer</b> has a capacity which is the size of the buffer and data size which is the size of the actual data in the buffer.
1734 The buffer is a continuous block of memory.
1735 The valid data is also a continuous block. The data can start at any offset in the buffer.
1736 */
1737 class MediaBuffer : public primo::Reference
1738 {
1739 public:
1740 /**
1741 Sets the offset at which valid data starts in the buffer block and the data size in bytes.
1742 The data offset and size are validated so that they are always within the buffer.
1743
1744 @param dataOffset The offset at which valid data starts in the buffer. Allowed values range from 0 to capacity()-1.
1745 @param dataSize The size of the valid data in the buffer. Allowed values range from 0 to capacity().
1746
1747 @return TRUE The data offset and size are successfully changed. FALSE The supplied data offset and size are not valid.
1748 */
1749 virtual bool_t setData(int32_t dataOffset, int32_t dataSize) = 0;
1750
1751 /**
1752 Returns the offset at which valid data starts in the buffer.
1753
1754 @return An offset that can range from 0 to capacity()-1.
1755 */
1756 virtual int32_t dataOffset() const = 0;
1757
1758 /**
1759 Returns the size of the valid data that in the buffer.
1760
1761 @return The data size in bytes. It ranges from 0 to capacity().
1762 */
1763 virtual int32_t dataSize() const = 0;
1764
1765 /**
1766 Returns a pointer to the first byte of data. This is effectively the same as start() + dataOffset().
1767
1768 @return A pointer to the data start.
1769 */
1770 virtual uint8_t* data() const = 0;
1771
1772 /**
1773 Returns a pointer to the start of the buffer.
1774
1775 @return A pointer to the buffer start. It is guaranteed that the pointer is valid only when capacity() is greater than 0.
1776 */
1777 virtual uint8_t* start() const = 0;
1778
1779 /**
1780 Returns the size of the buffer in bytes.
1781
1782 @return Buffer capacity. Can be zero.
1783 */
1784 virtual int32_t capacity() const = 0;
1785
1786 /**
1787 Allocates internal buffer storage
1788
1789 @param size Requested buffer size.
1790 A buffer storage is allocated only if the requested <i>size</i> exceeds the current buffer size (capacity).
1791 The actual allocated buffer may be larger than the requested <i>size<i>.
1792
1793 @param keepData Specifies whether to keep the existing data when the existing buffer is resized.
1794
1795 @return TRUE The allocation request succeeded. FALSE The allocation failed (out of memory).
1796
1797 @remarks If an external storage is attached it is automatically detached.
1798 */
1799 virtual bool_t alloc(int32_t size, bool_t keepData) = 0;
1800
1801 // TBR:
1802 // Python:
1803 // Plus:
1804 /**
1805 Allocates internal buffer storage with specified memory alignment.
1806
1807 @param alignment Memory alignment in bytes. Must be a power of 2 and at least 8 bytes.
1808 @param size Requested buffer size.
1809 A buffer storage is allocated only if the requested <i>size</i> exceeds the current buffer size (capacity).
1810
1811 @param keepData Specifies whether to keep the existing data when the existing buffer is resized.
1812
1813 @return TRUE The allocation request succeeded. FALSE The allocation failed (out of memory or invalid alignment).
1814
1815 @remarks If an external storage is attached it is automatically detached.
1816 The aligned allocation is tracked internally and the buffer is freed using the appropriate method.
1817 The minimum alignment of 8 bytes is required for compatibility with platform memory alignment functions.
1818
1819 @version 3.4
1820 */
1821 virtual bool_t alignedAlloc(int32_t alignment, int32_t size, bool_t keepData) = 0;
1822
1823 /**
1824 Frees internal buffer storage
1825
1826 @remarks The function does nothing if an external storage is attached to the buffer.
1827 */
1828 virtual void free() = 0;
1829
1830 /**
1831 Attaches an external buffer storage
1832
1833 @param buffer A pointer to the buffer storage.
1834
1835 @param size The buffer size.
1836
1837 @param setData Specifies whether to auto set data with a size equal to the buffer size.
1838 If TRUE the data size is set to the buffer size. If FALSE data size is 0.
1839
1840 @return TRUE The buffer is attached succefully, FALSE otherwise.
1841
1842 @remarks If an internal storage is already allocated it is automatically freed.
1843 */
1844 virtual bool_t attach(void* buffer, int32_t size, bool_t setData) = 0;
1845
1846 /**
1847 Detaches an external buffer storage
1848
1849 @return A pointer to the detached buffer storage. <b>NULL</b> if no external storage has been attached.
1850 */
1851 virtual uint8_t* detach() = 0;
1852
1853 /**
1854 Returns whether the MediaBuffer uses an external data buffer.
1855
1856 @return TRUE An external data buffer is attached to this MediaBuffer, FALSE otherwise.
1857 */
1858 virtual bool_t external() const = 0;
1859
1860 /**
1861 Clears existing data.
1862
1863 @remarks The operation does not change the buffer capacity.
1864 */
1865 virtual void clear() = 0;
1866
1867 /**
1868 Appends data to the end of the MediaBuffer data.
1869
1870 @param data A pointer to the data that should be appended.
1871
1872 @param dataSize The number of bytes that should be appended.
1873
1874 @return TRUE The operation is successful, FALSE otherwise.
1875
1876 @remarks If MediaBuffer has internal storage it will be increased if needed to fit the <i>data</i>.
1877 If MediaBuffer has external storage and the provided data cannot fit the operation will fail.
1878 */
1879 virtual bool_t append(const void* data, int32_t dataSize) = 0;
1880
1881 /**
1882 Removes data from the beginning of the MediaBuffer data.
1883
1884 @param dataSize The number of bytes that should be removed from the valid data.
1885
1886 @return TRUE The operation is successful, FALSE otherwise.
1887
1888 @remarks The operation does not change the buffer capacity.
1889 */
1890 virtual void remove(int32_t dataSize) = 0;
1891
1892 /**
1893 Moves the existing data to the start of the buffer amd maximizes the free linear space.
1894
1895 @remarks This may be useful when new data is added through direct copying after the existing data
1896 and then setData is used to extend/modify the data range.
1897 The operation does not change the buffer capacity.
1898 */
1899 virtual void normalize() = 0;
1900
1901 /**
1902 Returns the free <b>linear</b> space that can be used to append data without normalization.
1903
1904 @return The size in bytes of the free linear space in the buffer.
1905 This is equal to capacity() - dataSize() - dataOffset().
1906
1907 @remarks The free linear space starts at data() + dataSize().
1908 It is less than or equal to freeSpace().
1909
1910 @see freeSpace
1911 */
1912 virtual int32_t freeLinearSpace() const = 0;
1913
1914 /**
1915 Returns the free space that can be used to append data without buffer reallocation.
1916
1917 @return The size in bytes of the free space in the buffer.
1918 This is equal to capacity() - dataSize().
1919
1920 @remarks The free space starts at data() + dataSize().
1921 It is greater than or equal to freeLinearSpace().
1922
1923 @see freeLinearSpace
1924 */
1925 virtual int32_t freeSpace() const = 0;
1926
1927 /**
1928 Creates a deep copy of this object.
1929
1930 @return A new MediaBuffer object. The caller is responsible for releasing the new object when it is not needed anymore.
1931 @return <b>NULL</b> if the object cannot be cloned because there's not enough memory.
1932
1933 @remarks
1934 Only the pointer to the external buffer is copied when MediaBuffer does not own its data buffer, i.e. uses external / attached data.
1935 On the contrary, when MediaBuffer owns its data, a new copy of the data is created.
1936
1937 @see \ref object_management "Object Management"
1938 @see MediaBuffer::external
1939 */
1940 virtual MediaBuffer* clone() const = 0;
1941
1942 protected:
1943 /**
1944 This object can be destroyed only by its implementation. The caller must use Reference::release.
1945
1946 @see \ref object_management "Object Management"
1947 */
1948 ~MediaBuffer() {}
1949
1950 };
1951
1952
1953 /**
1954 MediaSample represents one or more samples of audio or video data.
1955 It is used for storing uncompressed or compressed data.
1956 */
1957 class MediaSample : public primo::Reference
1958 {
1959
1960 public:
1961
1962 /**
1963 Returns the buffer associated with this sample.
1964
1965 @return A pointer to a MediaBuffer object. Can be <b>NULL</b>.
1966 */
1967 virtual MediaBuffer* buffer() = 0;
1968
1969 /**
1970 Sets a new MediaBuffer object.
1971 The old MediaBuffer object is released. The new one is retained.
1972
1973 @param buffer A pointer to the new MediaBuffer object. Can be <b>NULL</b>.
1974 */
1975 virtual void setBuffer(MediaBuffer* buffer) = 0;
1976
1977 /**
1978 Resets the sample to its default values and clears the data in the buffer.
1979 */
1980 virtual void reset() = 0;
1981
1982 /**
1983 Returns the presentation timestamp (PTS) of the media sample.
1984
1985 @return time in seconds
1986 */
1987 virtual double startTime() const = 0;
1988
1989 /**
1990 Returns the end time of the media sample.
1991
1992 @return The time when the sample should end. Time in seconds.
1993
1994 @remarks The end time is optional and is valid only if it is greater than the start time.
1995 */
1996 virtual double endTime() const = 0;
1997
1998 /**
1999 Sets presentation timestamp (PTS) of the media sample.
2000
2001 @param time in seconds
2002
2003 */
2004 virtual void setStartTime(double time) = 0;
2005
2006 /**
2007 Sets the end time of the media sample.
2008
2009 @param time [in] The time when the sample should end. Time is in seconds.
2010
2011 @remarks The end time is optional and is valid only if it is greater than the start time.
2012 */
2013
2014 virtual void setEndTime(double time) = 0;
2015
2016 /**
2017 Returns the media sample flags.
2018
2019 @return A combination of flags defined in MediaSampleFlags::Enum.
2020 */
2021 virtual int32_t flags() const = 0;
2022
2023 /**
2024 Sets the media sample flags.
2025
2026 @param flags [in] A combination of flags defined in MediaSampleFlags::Enum.
2027 */
2028 virtual void setFlags(int32_t flags) = 0;
2029
2030 /**
2031 Sets the elementary stream to which the sample belongs.
2032
2033 @param streamNumber [in] A zero-based index of the elementary stream in the container.
2034 */
2035 virtual void setStreamNumber(int32_t streamNumber) = 0;
2036
2037 /**
2038 Returns the elementary stream to which the sample belongs.
2039
2040 @return A zero-based index of the elementary stream in the container.
2041 */
2042 virtual int32_t streamNumber() const = 0;
2043
2044
2045 /**
2046 Sets the required picture type (I/P/B/etc.).
2047
2048 @param pictureType [in] A constant from the PictureType::Enum.
2049
2050 @note Currently this is ignored by all encoders.
2051 */
2052 virtual void setPictureType(PictureType::Enum pictureType) = 0;
2053
2054 /**
2055 Returns the picture type (I/P/B/etc.) of demuxed, decoded, or encoded frame.
2056
2057 @return A constant from the PictureType::Enum.
2058
2059 @note Currently this is returned only by the MPEG-2 encoder.
2060 */
2061 virtual PictureType::Enum pictureType() const = 0;
2062
2063 // TBR:
2064 // Plus:
2065 /**
2066 Set the Frame Type object
2067
2068 @param frameType [in] A constant from the FrameType::Enum.
2069
2070 @note Currently this is used only by G.711 a-law and u-law codecs.
2071
2072 @version 3.2
2073 */
2074 virtual void setFrameType(FrameType::Enum frameType) = 0;
2075
2076 // TBR:
2077 // Plus:
2078 /**
2079 Returns the frame type of demuxed, decoded, or encoded frame.
2080
2081 @return A constant from the FrameType::Enum.
2082
2083 @note Currently this is used only by G.711 a-law and u-law codecs.
2084
2085 @version 3.2
2086 */
2087 virtual FrameType::Enum frameType() const = 0;
2088
2089 /**
2090 Creates a deep copy of this object.
2091
2092 @return A new MediaSample object.
2093 The caller is responsible for releasing the new object when it's not needed anymore.
2094
2095 @return <b>NULL</b> if the object cannot be cloned because there is not enough memory.
2096
2097 @see \ref object_management "Object Management"
2098 */
2099 virtual MediaSample* clone() const = 0;
2100
2101 /**
2102 Calculates the exact number of bytes that are needed
2103 for a video frame with the specified properties
2104
2105 @param frameWidth [in] frame width in pixels.
2106 @param frameHeight [in] frame height in pixels.
2107 @param colorFormat [in] the color format represents how colors are coded in the video frame.
2108
2109 @return The number of bytes needed to store a video frame with the specified properties.
2110 Zero if it is not possible to calculate the video frame buffer size from the supplied arguments.
2111 */
2112 virtual int32_t videoBufferSizeInBytes(int32_t frameWidth,
2113 int32_t frameHeight,
2114 ColorFormat::Enum colorFormat) const = 0;
2115
2116 protected:
2117 /**
2118 This object can be destroyed only by its implementation. The caller must use Reference::release.
2119
2120 @see \ref object_management "Object Management"
2121 */
2122 ~MediaSample() {}
2123
2124 };
2125
2126
2127 /**
2128 Defines media types.
2129 */
2130 namespace MediaType
2131 {
2132 /**
2133 MediaType::Enum
2134 */
2135 enum Enum
2136 {
2137 /** The media type is unknown or not specified. */
2138 Unknown = 0,
2139
2140 /** Audio data. */
2141 Audio = 1,
2142
2143 /** Video data */
2144 Video = 2,
2145
2146 /** Text data */
2147 Text = 3,
2148
2149 /** Generic data */
2150 Data = 4,
2151 };
2152 }
2153
2154
2155 /**
2156 Provides properties and operations that are common for all elementary streams.
2157
2158 AudioStreamInfo and VideoStreamInfo inherit from this interface.
2159
2160 @see AudioStreamInfo
2161 @see VideoStreamInfo
2162 */
2163 class StreamInfo : public primo::Reference
2164 {
2165 public:
2166 /**
2167 Returns the stream media type. The media type of a StreamInfo object cannot be changed.
2168
2169 @return media type
2170
2171 If the media type is MediaType::Audio this StreamInfo object can be safely cast to AudioStreamInfo.
2172
2173 If the media type is MediaType::Video this StreamInfo object can be safely cast to VideoStreamInfo.
2174 */
2175 virtual MediaType::Enum mediaType() const = 0;
2176
2177 /**
2178 Returns the stream type.
2179
2180 @return stream type
2181 */
2182 virtual StreamType::Enum streamType() const = 0;
2183
2184 /**
2185 Sets the stream type.
2186
2187 @param type major stream type.
2188
2189 @return TRUE if the stream type is successfully set, otherwise FALSE.
2190 */
2191 virtual bool_t setStreamType(StreamType::Enum type) = 0;
2192
2193 /**
2194 Returns the stream subtype.
2195
2196 @return stream subtype
2197 */
2198 virtual StreamSubType::Enum streamSubType() const = 0;
2199
2200 /**
2201 Sets the stream subtype.
2202
2203 @param type stream subtype.
2204
2205 @return TRUE if the stream subtype is successfully set, otherwise FALSE.
2206 */
2207 virtual bool_t setStreamSubType(StreamSubType::Enum type) = 0;
2208
2209 /**
2210 Returns the stream duration.
2211
2212 @return duration in seconds
2213 */
2214 virtual double duration() const = 0;
2215
2216 /**
2217 Sets the stream duration in seconds.
2218
2219 @param duration in seconds
2220
2221 @return TRUE if the duration is successfully set, otherwise FALSE.
2222 */
2223 virtual bool_t setDuration(double duration) = 0;
2224
2225 /**
2226 Returns the ID of the elementary stream.
2227
2228 @return stream id
2229 */
2230 virtual int32_t ID() const = 0;
2231
2232 /**
2233 Sets the ID of the elementary stream.
2234
2235 @param id elementary stream id
2236
2237 @return TRUE if the ID is successfully set, otherwise FALSE.
2238 */
2239 virtual bool_t setID(int32_t id) = 0;
2240
2241 /**
2242 Returns the number of the program to which the elementary stream belongs.
2243
2244 @return program number
2245
2246 @warning If the elementary stream is shared by 2 or more programs this property
2247 will return the last parsed program that uses this stream.
2248 */
2249 virtual int32_t programNumber() const = 0;
2250
2251 /**
2252 Sets the program to which the elementary stream belongs.
2253
2254 @param programNumber program number
2255
2256 @return TRUE if the program number is successfully set, otherwise FALSE.
2257 */
2258 virtual bool_t setProgramNumber(int32_t programNumber) = 0;
2259
2260 /**
2261 Returns the stream bitrate.
2262
2263 @return bitrate in bits per second.
2264 */
2265 virtual int32_t bitrate() const = 0;
2266
2267 /**
2268 Sets the stream bitrate.
2269
2270 @param bitrate the bitrate is expressed in bits per second.
2271
2272 @return TRUE if the bitrate is successfully set, otherwise FALSE.
2273 */
2274 virtual bool_t setBitrate(int32_t bitrate) = 0;
2275
2276 /**
2277 Returns the stream bitrate mode.
2278
2279 @return A BitrateMode::Enum constant.
2280 */
2281 virtual int32_t bitrateMode() const = 0;
2282
2283 /**
2284 Sets the stream bitrate mode.
2285
2286 @param bitrateMode A BitrateMode::Enum constant.
2287
2288 @return TRUE if the bitrate mode is successfully set, otherwise FALSE.
2289 */
2290 virtual bool_t setBitrateMode(int32_t bitrateMode) = 0;
2291
2292
2293 /**
2294 Creates a copy of this object.
2295
2296 @return A new StreamInfo object that has the same dynamic type as the cloned object.
2297
2298 When the object is cloned the full underlying object is copied.
2299
2300 For example if a StreamInfo object is actually an instance of AudioStreamInfo and is cloned,
2301 the new object is also an instance of AudioStreamInfo.
2302
2303 The caller is responsible for releasing the new object when it is not needed anymore.
2304
2305 @remarks
2306 When cloned an immutable object becomes mutable.
2307
2308 @see \ref object_management "Object Management"
2309 */
2310 virtual StreamInfo* clone() const = 0;
2311
2312 /**
2313 Copies the state of the current object to a destination object of the same type.
2314 The reference count of the source and the destination is not modified.
2315
2316 @param destination [out] A pointer to the destination object
2317
2318 @return TRUE The object state is copied, FALSE otherwise.
2319 */
2320 virtual bool_t copyTo(StreamInfo* destination) const = 0;
2321
2322
2323 /**
2324 Resets the stream information to its default state.
2325
2326 The full underlying object is reset. The media type of the stream is never reset.
2327
2328 @return TRUE The object is sucessfully reset.
2329 @return FALSE The object is immutable and cannot be reset.
2330 */
2331 virtual bool_t reset() = 0;
2332
2333 /**
2334 Returns whether the object is immutable.
2335 An immmutable object cannot be modified and all modifying methods fail to produce a result.
2336
2337 @return TRUE if the object is immutable, FALSE otherwise.
2338
2339 @remarks
2340 An immutable object <b>can</b> be modified by the AVBlocks library.
2341
2342 @remarks
2343 Object immutability spreads to all nested objects.
2344 Therefore it is not possible to add/set an immutable object to a mutable object.
2345
2346 @remarks
2347 When cloned an immutable object becomes mutable.
2348 */
2349 virtual bool_t immutable() const = 0;
2350
2351 // TBR:
2352 // C++:
2353 // Python:
2354 /**
2355 Returns decoder specific configuration data.
2356 This data is typically obtained from a demuxer and is required for decoding certain stream types.
2357
2358 @return A pointer to a MediaBuffer object containing the configuration data, or NULL if not set.
2359 @version 3.3
2360 */
2361 virtual MediaBuffer* configData() const = 0;
2362
2363 // TBR:
2364 // C++:
2365 // Python:
2366 /**
2367 Sets decoder specific configuration data.
2368
2369 @param configData A pointer to a MediaBuffer object containing the configuration data. Can be NULL.
2370 @version 3.3
2371 */
2372 virtual void setConfigData(MediaBuffer* configData) = 0;
2373
2374 protected:
2375 /**
2376 This object can be destroyed only by its implementation. The caller must use Reference::release.
2377
2378 @see \ref object_management "Object Management"
2379 */
2380 ~StreamInfo() {}
2381 };
2382
2383 /**
2384 StreamInfoEnum is a read-only collection of StreamInfo objects.
2385 */
2386 class StreamInfoEnum : public primo::Reference
2387 {
2388 public:
2389 /**
2390 Returns the number of StreamInfo objects in the collection.
2391
2392 @return number of objects.
2393 */
2394 virtual int32_t count() const = 0;
2395
2396 /**
2397 Returns the stream information for the specified item.
2398
2399 @param index [in] The stream index in the collection.
2400
2401 @return A pointer to a StreamInfo object specified by index or <b>NULL</b> if the index is invalid.
2402
2403 The caller is not required to release the returned object.
2404
2405 @see \ref object_management "Object Management"
2406
2407 */
2408 virtual primo::codecs::StreamInfo* at(int32_t index) const = 0;
2409
2410 protected:
2411 /**
2412 This object can be destroyed only by the AVBlocks library.
2413 */
2414 ~StreamInfoEnum() {}
2415
2416 };
2417
2418 /**
2419 AudioStreamInfo describes an elementary audio stream.
2420 */
2421 class AudioStreamInfo : public StreamInfo
2422 {
2423
2424 public:
2425
2426 /**
2427 Returns the audio format flags which describe various properties of the audio stream.
2428
2429 @return A combination of flags defined in PcmFlags::Enum.
2430 */
2431 virtual int32_t pcmFlags() const = 0;
2432
2433
2434 /**
2435 Sets the audio format flags which describe various properties of the audio stream.
2436
2437 @param flags A combination of flags defined in PcmFlags::Enum.
2438
2439 @return TRUE if the flags are successfully set, otherwise FALSE.
2440 */
2441 virtual bool_t setPcmFlags(int32_t flags) = 0;
2442
2443 /**
2444 Returns the number of audio channels.
2445
2446 @return Number of channels.
2447 */
2448 virtual int32_t channels() const = 0;
2449
2450 /**
2451 Sets the number of audio channels.
2452
2453 @param numChannels number of channels.
2454
2455 @return TRUE if the number of channels is successfully set, otherwise FALSE.
2456 */
2457 virtual bool_t setChannels(int32_t numChannels) = 0;
2458
2459 /**
2460 Returns the channel layout which defines the mapping between channels and speakers.
2461
2462 @return A combination of flags defined in the AudioChannelFlags::Enum.
2463 */
2464 virtual int32_t channelLayout() const = 0;
2465
2466 /**
2467 Sets the channel layout which defines the mapping between channels and speakers.
2468
2469 @param channelLayout A combination of flags defined in the AudioChannelFlags::Enum.
2470
2471 @return TRUE if the channel layout is successfully set, otherwise FALSE.
2472 */
2473 virtual bool_t setChannelLayout(int32_t channelLayout) = 0;
2474
2475 /**
2476 Returns the audio sample rate.
2477
2478 @return sample rate (Hz)
2479 */
2480 virtual int32_t sampleRate() const = 0;
2481
2482 /**
2483 Sets the audio sample rate.
2484
2485 @param sampleRate sample rate (Hz)
2486
2487 @return TRUE if the sample rate is successfully set, otherwise FALSE.
2488 */
2489 virtual bool_t setSampleRate(int32_t sampleRate) = 0;
2490
2491 /**
2492 Returns the number of bits per sample (sample resolution).
2493
2494 @return bits per sample (usually 8, 16, 24 or 32).
2495
2496 Normally bits per sample is not defined for a compressed audio stream and is 0.
2497 However it is possible for a compressed audio stream to return a positive value as an indication
2498 of audio quality. It can also designate the bits per sample of the LPCM stream once the compressed stream is decoded.
2499 */
2500 virtual int32_t bitsPerSample() const = 0;
2501
2502 /**
2503 Sets the number of bits per sample (sample resolution).
2504
2505 @param bitsPerSample (usually 8, 16, 24 or 32)
2506
2507 @return TRUE if the number of bits per sample is successfully set, otherwise FALSE.
2508 */
2509 virtual bool_t setBitsPerSample(int32_t bitsPerSample) = 0;
2510
2511 /**
2512 Returns the number of bytes occupied by an audio frame (smallest discrete unit).
2513
2514 @return bytes per frame.
2515
2516 A frame is the smallest unit in an audio stream. It may contain one or more samples.
2517 Depending on the audio stream type the frame may contain fixed or variable number of samples.
2518
2519 For compressed streams the frame size is variable even if there are fixed number of samples in each frame.
2520 In this case bytes per frame is 0.
2521
2522 For an LCPM stream the frame size is constant.
2523 In this case bytes per frame is a positive value.
2524 Normally for interleaved LPCM streams the following is true:
2525 - bytesPerFrame() / channels() == (sample size in bytes)
2526 - The valid bits in a sample are given by bitsPerSample() and they are aligned towards the hi-order byte.
2527
2528 @return TRUE if bytes per sample is successfully set, otherwise FALSE.
2529 */
2530 virtual int32_t bytesPerFrame() const = 0;
2531
2532 /**
2533 Sets the number of bytes occupied by an audio frame (smallest discrete unit).
2534
2535 @param bytesPerFrame [in] Specifies how many bytes are occupied by each audio frame.
2536 Normally it is valid (greater than 0) for LPCM streams and invalid (0) for compressed audio streams.
2537
2538 @return TRUE if the number of bytes per frame is successfully set, otherwise FALSE.
2539 */
2540 virtual bool_t setBytesPerFrame(int32_t bytesPerFrame) = 0;
2541
2542 /**
2543 Copies the state of the current object to a destination object of the same type.
2544 The reference count of the source and the destination is not modified.
2545
2546 @param destination [out] A pointer to the destination object
2547
2548 @return TRUE if the object state is copied, FALSE otherwise.
2549 */
2550 virtual bool_t copyTo(AudioStreamInfo * destination) const = 0;
2551
2552 /**
2553 Creates a copy of this object.
2554
2555 @return A new AudioStreamInfo.
2556 The caller is responsible for releasing the new object when it is not needed anymore.
2557
2558 @see \ref object_management "Object Management"
2559 */
2560 virtual AudioStreamInfo* clone() const = 0;
2561
2562 protected:
2563 /**
2564 This object can be destroyed only by its implementation. The caller must use Reference::release.
2565
2566 @see \ref object_management "Object Management"
2567 */
2568 ~AudioStreamInfo() {}
2569 };
2570
2571 /**
2572 VideoStreamInfo describes an elementary video stream.
2573 */
2574 class VideoStreamInfo : public StreamInfo
2575 {
2576
2577 public:
2578
2579 /**
2580 Returns the video frame width.
2581
2582 @return video frame width in pixels.
2583 */
2584 virtual int32_t frameWidth() const = 0;
2585
2586 /**
2587 Sets the video frame width.
2588
2589 @param frameWidth in pixels.
2590
2591 @return TRUE if the frame width is successfully set, otherwise FALSE.
2592 */
2593 virtual bool_t setFrameWidth(int32_t frameWidth) = 0;
2594
2595 /**
2596 Returns the video frame height.
2597
2598 @return video frame height in pixels.
2599 */
2600 virtual int32_t frameHeight() const = 0;
2601
2602 /**
2603 Sets the video frame height.
2604
2605 @param frameHeight in pixels
2606
2607 @return TRUE if the frame height is successfully set, otherwise FALSE.
2608 */
2609 virtual bool_t setFrameHeight(int32_t frameHeight) = 0;
2610
2611 /**
2612 Returns the vertical dimension of the display aspect ratio.
2613
2614 @return vertical display ratio.
2615 */
2616 virtual int32_t displayRatioHeight() const = 0;
2617
2618 /**
2619 Returns the horizontal dimension of the display aspect ratio.
2620
2621 @return horizontal display ratio.
2622 */
2623 virtual int32_t displayRatioWidth() const = 0;
2624
2625 /**
2626 Sets the vertical dimension of the display aspect ratio.
2627
2628 @param displayHeight The value has no meaning on its own. It serves only to express the display aspect ratio.
2629
2630 @return TRUE if the display height is successfully set, otherwise FALSE.
2631 */
2632 virtual bool_t setDisplayRatioHeight(int32_t displayHeight) = 0;
2633
2634 /**
2635 Sets the horizontal dimension of the display aspect ratio.
2636
2637 @param displayWidth The value has no meaning on its own. It serves only to express the display aspect ratio.
2638
2639 @return TRUE if the display width is successfully set, otherwise FALSE.
2640 */
2641 virtual bool_t setDisplayRatioWidth(int32_t displayWidth) = 0;
2642
2643 /**
2644 Returns the video frame rate.
2645
2646 @return video frame rate in frames per second.
2647 */
2648 virtual double frameRate() const = 0;
2649
2650 /**
2651 Sets the video frame rate.
2652
2653 @param frameRate in frames per second.
2654
2655 @return TRUE if the frame rate is successfully set, otherwise FALSE.
2656 */
2657 virtual bool_t setFrameRate(double frameRate) = 0;
2658
2659 /**
2660 Returns the video color format.
2661
2662 @return A ColorFormat::Enum constant.
2663 */
2664 virtual ColorFormat::Enum colorFormat() const = 0;
2665
2666 /**
2667 Sets the video color format.
2668
2669 @param colorFormat color format
2670
2671 @return TRUE if the color format is successfully set, otherwise FALSE.
2672 */
2673 virtual bool_t setColorFormat(ColorFormat::Enum colorFormat) = 0;
2674
2675 /**
2676 Returns the video image stride.
2677
2678 @return Image stride in bytes.
2679
2680 <i><b>Stride</b></i> is the distance in bytes from the start of one row of pixels in memory to the start of the next row of pixels.
2681 It is also called a <i><b>pitch</b></i>.
2682 */
2683 virtual int32_t stride() const = 0;
2684
2685 /**
2686 Sets the video image stride.
2687
2688 @param stride Image stride in bytes.
2689
2690 <i><b>Stride</b></i> is the distance in bytes from the start of one row of pixels in memory to the start of the next row of pixels.
2691 It is also called a <i><b>pitch</b></i>.
2692
2693 @return TRUE if the stride is successfully set, otherwise FALSE.
2694 */
2695 virtual bool_t setStride(int32_t stride) = 0;
2696
2697 /**
2698 Returns the scan type of the video frame.
2699
2700 @return Scan type
2701 */
2702 virtual ScanType::Enum scanType() const = 0;
2703
2704 /**
2705 Sets the scan type of the video frame.
2706
2707 @param scanType
2708
2709 @return TRUE The scan type is set, FALSE otherwise.
2710 */
2711 virtual bool_t setScanType(ScanType::Enum scanType) = 0;
2712
2713 /**
2714 Returns whether internally the video frame is stored upside down.
2715
2716 @return TRUE The frame is stored upside down (vertically flipped) but logically it should be displayed normally.
2717 This is typical for bitmaps. FALSE The frame is displayed as it is stored - top row is first in memory, bottom row is last.
2718 */
2719 virtual bool_t frameBottomUp() const = 0;
2720
2721 /**
2722 Sets whether internally the video frame is stored upside down.
2723
2724 @param bottomUp TRUE the frame is stored upside down, FALSE the frame is stored normally
2725
2726 @return TRUE if the bottom-up flag is successfully set, otherwise FALSE.
2727 */
2728 virtual bool_t setFrameBottomUp(bool_t bottomUp) = 0;
2729
2730 /**
2731 Copies the state of the current object to a destination object of the same type.
2732 The reference count of the source and the destination is not modified.
2733
2734 @param destination [out] A pointer to the destination object
2735
2736 @return TRUE The object state is copied, FALSE otherwise.
2737 */
2738 virtual bool_t copyTo(VideoStreamInfo * destination) const = 0;
2739
2740 /**
2741 Creates a copy of this object.
2742
2743 @return A new VideoStreamInfo.
2744 The caller is responsible for releasing the new object when it is not needed anymore.
2745
2746 @remarks
2747 When cloned an immutable object becomes mutable.
2748
2749 @see \ref object_management "Object Management"
2750 */
2751 virtual VideoStreamInfo* clone() const = 0;
2752
2753 protected:
2754 /**
2755 This object can be destroyed only by its implementation. The caller must use Reference::release.
2756
2757 @see \ref object_management "Object Management"
2758 */
2759 ~VideoStreamInfo() {}
2760 };
2761
2762
2763 /**
2764 DataStreamInfo describes a generic data stream.
2765 */
2766 /*class DataStreamInfo : public StreamInfo
2767 {
2768
2769 };*/
2770
2771
2772 ///
2773 /// Metadata
2774 ///
2775
2776 /**
2777 Metadata attribute names
2778 */
2779 namespace Meta
2780 {
2781 /** Comment */
2782 static const char Comment[] = "Comment";
2783
2784 /** Involved people */
2785 static const char InvolvedPeople[] = "InvolvedPeople";
2786
2787 /** Play counter */
2788 static const char PlayCounter[] = "PlayCounter";
2789
2790 /** Popularity meter / rating */
2791 static const char Popularimeter[] = "Popularimeter";
2792
2793 /** Album */
2794 static const char Album[] = "Album";
2795
2796 /** Composer */
2797 static const char Composer[] = "Composer";
2798
2799 /** Genre */
2800 static const char Genre[] = "Genre";
2801
2802 /** Copyright */
2803 static const char Copyright[] = "Copyright";
2804
2805 /** Date (YYYY-MM-DD) */
2806 static const char Date[] = "Date";
2807
2808 /** Encoding software */
2809 static const char EncodedBy[] = "EncodedBy";
2810
2811 /** Lyricist / text writer */
2812 static const char Lyricist[] = "Lyricist";
2813
2814 /** File type */
2815 static const char FileType[] = "FileType";
2816
2817 /** Time */
2818 static const char Time[] = "Time";
2819
2820 /** Content group */
2821 static const char ContentGroup[] = "ContentGroup";
2822
2823 /** Title */
2824 static const char Title[] = "Title";
2825
2826 /** Subtitle */
2827 static const char Subtitle[] = "Subtitle";
2828
2829 /** Language */
2830 static const char Language[] = "Language";
2831
2832 /** Media type */
2833 static const char MediaType[] = "MediaType";
2834
2835 /** Original album */
2836 static const char OrigAlbum[] = "OrigAlbum";
2837
2838 /** Original file name */
2839 static const char OrigFileName[] = "OrigFileName";
2840
2841 /** Original lyricist / text writer */
2842 static const char OrigLyricist[] = "OrigLyricist";
2843
2844 /** Original artist */
2845 static const char OrigArtist[] = "OrigArtist";
2846
2847 /** Lead artist */
2848 static const char LeadArtist[] = "LeadArtist";
2849
2850 /** Album artist */
2851 static const char AlbumArtist[] = "AlbumArtist";
2852
2853 /** Conductor */
2854 static const char Conductor[] = "Conductor";
2855
2856 /** Remix / cover artist */
2857 static const char RemixArtist[] = "RemixArtist";
2858
2859 /** Disc number is 1-based */
2860 static const char DiscNum[] = "DiscNum";
2861
2862 /** Publisher */
2863 static const char Publisher[] = "Publisher";
2864
2865 /** Track number is 1-based */
2866 static const char TrackNum[] = "TrackNum";
2867
2868 /** Recording dates */
2869 static const char RecordingDates[] = "RecordingDates";
2870
2871 /** Internet radio station name */
2872 static const char InternetRadioStation[] = "InternetRadioStation";
2873
2874 /** Encoding software settings */
2875 static const char EncoderSettings[] = "EncoderSettings";
2876
2877 /** Year only (YYYY) */
2878 static const char Year[] = "Year";
2879
2880 /** User text */
2881 static const char UserText[] = "UserText";
2882
2883 /** Unsynced lyrics */
2884 static const char UnsyncedLyrics[] = "UnsyncedLyrics";
2885
2886 /**
2887 URL pointing at a web page with information such as where the album can be bought.
2888 */
2889 static const char UrlCommercialInfo[] = "UrlCommercialInfo";
2890
2891 /**
2892 URL pointing at a web page where the terms of use and ownership of the file is described.
2893 */
2894 static const char UrlCopyright[] = "UrlCopyright";
2895
2896 /**
2897 URL pointing at a file specific web page.
2898 */
2899 static const char UrlAudioFile[] = "UrlAudioFile";
2900
2901 /**
2902 URL pointing at the artist's official web page.
2903 There may be more than one attributes with this name if the audio contains more than one performer.
2904 */
2905 static const char UrlArtist[] = "UrlArtist";
2906
2907 /**
2908 URL pointing at the official web page for the source of the audio file, e.g. a movie.
2909 */
2910 static const char UrlAudioSource[] = "UrlAudioSource";
2911
2912 /**
2913 URL pointing at the homepage of the Internet radio station.
2914 */
2915 static const char UrlRadioPage[] = "UrlRadioPage";
2916
2917 /**
2918 URL pointing at a web page that will handle the process of paying for this file.
2919 */
2920 static const char UrlPayment[] = "UrlPayment";
2921
2922 /**
2923 URL pointing at the official web page for the publisher.
2924 */
2925 static const char UrlPublisher[] = "UrlPublisher";
2926
2927 /** User URL */
2928 static const char UrlUser[] = "UrlUser";
2929
2930 /** Private comment */
2931 static const char Private[] = "Private";
2932
2933 /** Beats per minute */
2934 static const char BeatsPerMinute[] = "BeatsPerMinute";
2935 }
2936
2937 /**
2938 Represents the meta picture (image) type.
2939
2940 @see MetaPicture::pictureType
2941 */
2942 namespace MetaPictureType
2943 {
2944 /**
2945 The picture type is defined as in ID3.
2946 */
2947 enum Enum
2948 {
2949 Other = 0,
2950
2951 /**
2952 32x32 pixels 'file icon' (PNG only); only one in a ID3 tag
2953 */
2954 FileIcon = 1,
2955
2956 /**
2957 Other icon; only one in a ID3 tag
2958 */
2959 OtherFileIcon = 2,
2960
2961 /**
2962 Front cover
2963 */
2964 FrontCover = 3,
2965
2966 /**
2967 Back cover
2968 */
2969 BackCover = 4,
2970
2971 /**
2972 Leaflet page
2973 */
2974 LeafletPage = 5,
2975
2976 /**
2977 The image is printed on the media (e.g. label side of CD)
2978 */
2979 Media = 6,
2980
2981 /**
2982 Lead artist / Lead performer/ Soloist
2983 */
2984 LeadArtist = 7,
2985
2986 /**
2987 Artist / Performer
2988 */
2989 Artist = 8,
2990
2991 /**
2992 Conductor
2993 */
2994 Conductor = 9,
2995
2996 /**
2997 Band / Orchestra
2998 */
2999 Band = 10,
3000
3001 /**
3002 Composer
3003 */
3004 Composer = 11,
3005
3006 /**
3007 Lyricist / Text writer
3008 */
3009 TextWriter = 12,
3010
3011 /**
3012 Recording location
3013 */
3014 RecordingLocation = 13,
3015
3016 /**
3017 A image taken during recording.
3018 */
3019 DuringRecording = 14,
3020
3021 /**
3022 A image taken during performance.
3023 */
3024 DuringPerformance = 15,
3025
3026 /**
3027 Movie / video screen capture.
3028 */
3029 VideoCapture = 16,
3030
3031 /**
3032 A brightly coloured fish :0
3033 */
3034 BrightColoredFish = 17,
3035
3036 /**
3037 Illustration
3038 */
3039 Illustration = 18,
3040
3041 /*
3042 Band / Artist logotype
3043 */
3044 ArtistLogotype = 19,
3045
3046 /*
3047 Publisher / Studio logotype
3048 */
3049 PublisherLogotype = 20,
3050 };
3051 }
3052
3053 /**
3054 Defines MIME types used by primo codecs components
3055 */
3056 namespace MimeType
3057 {
3058 /** GIF MIME type */
3059 static const char Gif[] = "image/gif";
3060
3061 /** JPEG MIME type */
3062 static const char Jpeg[] = "image/jpeg";
3063
3064 /** PNG MIME type */
3065 static const char Png[] = "image/png";
3066
3067 /** TIFF MIME type */
3068 static const char Tiff[] = "image/tiff";
3069 }
3070
3071
3072 /**
3073 MetaPicture describes a meta image that is part of an audio or video file.
3074
3075 @see Library::createMetaPicture
3076 @see Metadata
3077 */
3078 class MetaPicture : public primo::Reference
3079 {
3080 public:
3081
3082 /**
3083 Creates a deep copy of this object.
3084
3085 @return A new MetaPicture object.
3086 The caller is responsible for releasing the new object when it's not needed anymore.
3087
3088 @return <b>NULL</b> if the object cannot be cloned because there is not enough memory.
3089
3090 @remarks
3091 When cloned an immutable object becomes mutable.
3092
3093 @see \ref object_management "Object Management"
3094 */
3095 virtual MetaPicture* clone() const = 0;
3096
3097 /**
3098 Returns the picture MIME type.
3099
3100 @return The MIME type is an ANSI string.
3101
3102 @see primo::codecs::MimeType
3103 */
3104 virtual const char* mimeType() const = 0;
3105
3106 /**
3107 Sets the picture MIME type.
3108
3109 @param mimeType [in] A pointer to ANSI string specifying the MIME type
3110
3111 @return TRUE if the MIME type is successfully set, otherwise FALSE.
3112
3113 @see primo::codecs::MimeType
3114 */
3115 virtual bool_t setMimeType(const char* mimeType) = 0;
3116
3117 /**
3118 Returns the meta picture type (front cover, back cover, artist, etc.)
3119
3120 @return A picture type constant defined in MetaPictureType::Enum.
3121
3122 @see MetaPictureType::Enum
3123 */
3124 virtual MetaPictureType::Enum pictureType() const = 0;
3125
3126 /**
3127 Sets the picture type (front cover, back cover, artist, etc.)
3128
3129 @param [in] picType A picture type constant defined in MetaPictureType::Enum.
3130
3131 @return TRUE if the picture type is successfully set, otherwise FALSE.
3132
3133 @see MetaPictureType::Enum
3134 */
3135 virtual bool_t setPictureType(MetaPictureType::Enum picType) = 0;
3136
3137 /**
3138 Returns a picture description as a free text.
3139
3140 @return Unicode string. Can be <b>NULL</b> if the picture has no description.
3141 */
3142 virtual const char_t* description() const = 0;
3143
3144 /**
3145 Sets picture description.
3146
3147 @param description [in] A pointer to a Unicode string. Can be <b>NULL</b> in which case the picture description is cleared.
3148
3149 @return TRUE if the description is successfully set, otherwise FALSE.
3150 */
3151 virtual bool_t setDescription(const char_t* description) = 0;
3152
3153 /**
3154 Returns the start of the image data.
3155 The image is a jpeg, png or another image type.
3156
3157 @return A pointer to the start of the image data.
3158 The number of image bytes is given by the MetaPicture::dataSize property.
3159 The image type (jpeg, png, etc.) is given by the MetaPicture::mimeType property.
3160
3161 @see MetaPicture::mimeType
3162 @see MetaPicture::dataSize
3163 */
3164 virtual const uint8_t* data() const = 0;
3165
3166 /**
3167 Returns the number of image bytes.
3168
3169 @return The number of image bytes that are returned by the MetaPicture::data property.
3170 */
3171 virtual int32_t dataSize() const = 0;
3172
3173 /**
3174 Sets image data.
3175
3176 @param data [in] A pointer to the new image data.
3177
3178 @param dataSize [in] The size of the new image in bytes .
3179
3180 @return TRUE if the data is successfully set, FALSE if there's an error.
3181
3182 The supplied <i>data</i> is copied internally and is not required to be valid after the method returns.
3183
3184 @see MetaPicture::data
3185 @see MetaPicture::dataSize
3186 */
3187 virtual bool_t setData(const void* data, int32_t dataSize) = 0;
3188
3189 /**
3190 Returns whether the object is immutable.
3191 An immmutable object cannot be modified and all modifying methods fail to produce a result.
3192
3193 @return TRUE if the object is immutable, FALSE otherwise.
3194
3195 @remarks
3196 An immutable object <b>can</b> be modified by the AVBlocks library.
3197
3198 @remarks
3199 Object immutability spreads to all nested objects.
3200 Therefore it is not possible to add/set an immutable object to a mutable object.
3201
3202 @remarks
3203 When cloned an immutable object becomes mutable.
3204 */
3205 virtual bool_t immutable() const = 0;
3206
3207 protected:
3208 /**
3209 This object can be destroyed only by the library that has created it.
3210
3211 @see primo::Reference::release
3212 */
3213 virtual ~MetaPicture() {};
3214 };
3215
3216
3217 /**
3218 MetaPictureList represents the meta pictures inside a Metadata object.
3219
3220 This is a modifiable and indexable collection that exists only in the context of a Metadata object
3221 and cannot be created separately from it, nor detached.
3222 */
3223 class MetaPictureList : public primo::Reference
3224 {
3225 public:
3226 /**
3227 Returns a picture by index.
3228
3229 @param index [in] A zero-based index.
3230
3231 @return A pointer to the MetaPicture object specified by <i>index</i>.
3232
3233 The caller is not required to release the returned object.
3234 */
3235 virtual MetaPicture* at(int32_t index) const = 0;
3236
3237 /**
3238 Adds a new picture to the end of the list.
3239
3240 @param picture [in] A pointer to a MetaPicture object.
3241 It is allowed to add a <b>NULL</b> item to the collection.
3242 Internally if the MetaPicture object is not <b>NULL</b> it is retained,
3243 so it is safe to release it after this method returns.
3244
3245 @return TRUE if the specified item is added to the collection, otherwise FALSE.
3246
3247 @see Library::createMetaPicture
3248 @see \ref object_management "Object Management"
3249
3250 */
3251 virtual bool_t add(MetaPicture* picture) = 0;
3252
3253 /**
3254 Returns the number of pictures in the list.
3255
3256 @return number of items in the collection.
3257 */
3258 virtual int32_t count() const = 0;
3259
3260 /**
3261 Removes all pictures from the collection.
3262
3263 When removed from the collection each MetaPicture object is released.
3264
3265 @return TRUE if the collection is cleared, otherwise FALSE.
3266
3267 @see \ref object_management "Object Management"
3268 */
3269 virtual bool_t clear() = 0;
3270
3271 /**
3272 Removes a picture by index.
3273
3274 @param index [in] A zero-based index of the picture that shall be removed. When the MetaPicture object is removed it is released.
3275
3276 @return TRUE if the picture is successfully removed, FALSE if there's an error.
3277
3278 @see primo::Reference::release
3279 */
3280 virtual bool_t remove(int32_t index) = 0;
3281
3282 /**
3283 Inserts a picture at the specified index in the list.
3284
3285 @param itemIndex [in] The index in the collection where the new item shall be inserted.
3286 This must be a valid index in the collection. Indexing starts from 0.
3287 After the new item is inserted in the collection its index is the value of the <i>itemIndex</i> param.
3288
3289 @param picture [in] A pointer to the MetaPicture object that shall be inserted.
3290 It is allowed to insert a <b>NULL</b> value in the collection.
3291 Internally the new item is retained (if not <b>NULL</b>), so it is safe to release it
3292 after this method returns.
3293
3294 @return TRUE The item is inserted, FALSE otherwise.
3295
3296 @see \ref object_management "Object Management"
3297 */
3298 virtual bool_t insert(int32_t itemIndex, MetaPicture* picture) = 0;
3299
3300 /**
3301 Sets a new picture at the specified index.
3302
3303 @param itemIndex [in] The index in the collection where the new item shall be set.
3304 This must be a valid index in the collection. Indexing starts from 0.
3305
3306 @param picture [in] A pointer to the MetaPicture object that shall be set.
3307 It is allowed to set a <b>NULL</b> value to the collection.
3308 Internally the new item is retained (if not <b>NULL</b>), so it is safe to release it
3309 after this method returns. The old item is released (if not <b>NULL</b>).
3310
3311 @return TRUE if the item is set, FALSE otherwise.
3312
3313 @see \ref object_management "Object Management"
3314 */
3315 virtual bool_t setAt(int32_t itemIndex, MetaPicture* picture) = 0;
3316
3317 /**
3318 Returns whether the object is immutable.
3319 An immmutable object cannot be modified and all modifying methods fail to produce a result.
3320
3321 @return TRUE if the object is immutable, FALSE otherwise.
3322
3323 @remarks
3324 An immutable object <b>can</b> be modified by the AVBlocks library.
3325
3326 @remarks
3327 Object immutability spreads to all nested objects.
3328 Therefore it is not possible to add/set an immutable object to a mutable object.
3329 */
3330 virtual bool_t immutable() const = 0;
3331
3332 protected:
3333 /**
3334 This object can be destroyed only by the library that has created it.
3335
3336 @see primo::Reference::release
3337 */
3338 virtual ~MetaPictureList() {};
3339 };
3340
3341
3342 /**
3343 MetaAttribute describes a textual meta information that is part of an audio or video file.
3344
3345 @see Library::createMetaAttribute
3346 @see Metadata
3347 */
3348 class MetaAttribute : public primo::Reference
3349 {
3350 public:
3351
3352 /**
3353 Creates a deep copy of this object.
3354
3355 @return A new MetaAttribute object.
3356 The caller is responsible for releasing the new object when it's not needed anymore.
3357
3358 @return <b>NULL</b> if the object cannot be cloned because there is not enough memory.
3359
3360 @remarks
3361 When cloned an immutable object becomes mutable.
3362
3363 @see \ref object_management "Object Management"
3364 */
3365 virtual MetaAttribute* clone() const = 0;
3366
3367 /**
3368 Returns the value of the meta attribute.
3369
3370 @return A pointer to a Unicode string.
3371 */
3372 virtual const char_t* value() const = 0;
3373
3374 /**
3375 Sets the value a meta attribute.
3376
3377 @param [in] val A pointer to a Unicode string.
3378
3379 @return TRUE if the value is successfully set, otherwise FALSE.
3380 */
3381 virtual bool_t setValue(const char_t* val) = 0;
3382
3383 /**
3384 Returns the name of the meta attribute.
3385
3386 @return A pointer to an ANSI string.
3387
3388 Common meta attribute names are defined in primo::codecs::Meta
3389
3390 @see primo::codecs::Meta
3391 */
3392 virtual const char* name() const = 0;
3393
3394 /**
3395 Sets the name of a meta attribute.
3396
3397 @param [in] name A pointer to an ANSI string.
3398
3399 Common meta attribute names are defined in primo::codecs::Meta
3400
3401 @return TRUE if the name is successfully set, otherwise FALSE.
3402
3403 @see primo::codecs::Meta
3404 */
3405 virtual bool_t setName(const char* name) = 0;
3406
3407 /**
3408 Returns whether the object is immutable.
3409 An immmutable object cannot be modified and all modifying methods fail to produce a result.
3410
3411 @return TRUE if the object is immutable, FALSE otherwise.
3412
3413 @remarks
3414 An immutable object <b>can</b> be modified by the AVBlocks library.
3415
3416 @remarks
3417 Object immutability spreads to all nested objects.
3418 Therefore it is not possible to add/set an immutable object to a mutable object.
3419
3420 @remarks
3421 When cloned an immutable object becomes mutable.
3422 */
3423 virtual bool_t immutable() const = 0;
3424
3425 protected:
3426 /**
3427 This object can be destroyed only by the library that has created it.
3428
3429 @see primo::Reference::release
3430 */
3431 virtual ~MetaAttribute() {};
3432
3433 };
3434
3435
3436 /**
3437 MetaAttributeList represents the meta attributes inside a Metadata object.
3438
3439 This is a modifiable and indexable collection that exists only in the context of a Metadata object
3440 and cannot be created separately from it, nor detached.
3441 */
3442 class MetaAttributeList : public primo::Reference
3443 {
3444 public:
3445
3446 /**
3447 Returns an attribute by index.
3448
3449 @param index [in] A zero-based index.
3450
3451 @return A pointer to the MetaAttribute object specified by <i>index</i>.
3452
3453 The caller is not required to release the returned object.
3454 */
3455 virtual MetaAttribute* at(int32_t index) const = 0;
3456
3457 /**
3458 Returns an attribute by name.
3459
3460 @param name [in] A pointer to the attribute name that is searched in the list. The name is an ANSI string.
3461
3462 @return A pointer to the first MetaAttribute object that matches the specified <i>name</i>.
3463
3464 The caller is not required to release the returned object.
3465
3466 @see primo::codecs::Meta
3467 */
3468 virtual MetaAttribute* itemByName(const char* name) const = 0;
3469
3470 /**
3471 Adds a new attribute to the end of the list.
3472
3473 @param attrib [in] A pointer to a MetaAttribute object.
3474 It is allowed to add a <b>NULL</b> item to the collection.
3475 Internally if the MetaAttribute object is not <b>NULL</b> it is retained,
3476 so it is safe to release it after this method returns.
3477
3478 @return TRUE if the specified item is added to the collection, otherwise FALSE.
3479
3480 @see Library::createMetaAttribute
3481 @see \ref object_management "Object Management"
3482
3483 */
3484 virtual bool_t add(MetaAttribute* attrib) = 0;
3485
3486 /**
3487 Returns the number of attributes in the list.
3488
3489 @return number of items in the collection.
3490 */
3491 virtual int32_t count() const = 0;
3492
3493 /**
3494 Removes all attributes from the collection.
3495
3496 When removed from the collection each MetaAttribute object is released.
3497
3498 @return TRUE if the collection is cleared, otherwise FALSE.
3499
3500 @see \ref object_management "Object Management"
3501 */
3502 virtual bool_t clear() = 0;
3503
3504 /**
3505 Removes an attribute by index.
3506
3507 @param index [in] A zero-based index of the attribute that shall be removed. When the MetaAttribute object is removed it is released.
3508
3509 @return TRUE if the attribute is successfully removed, FALSE if there's an error.
3510 */
3511 virtual bool_t remove(int32_t index) = 0;
3512
3513 /**
3514 Inserts an attribute at the specified index in the list.
3515
3516 @param itemIndex [in] The index in the collection where the new item shall be inserted.
3517 This must be a valid index in the collection. Indexing starts from 0.
3518 After the new item is inserted in the collection its index is the value of the <i>itemIndex</i> param.
3519
3520 @param attrib [in] A pointer to the MetaAttribute object that shall be inserted.
3521 It is allowed to insert a <b>NULL</b> value in the collection.
3522 Internally the new item is retained (if not <b>NULL</b>), so it is safe to release it
3523 after this method returns.
3524
3525 @return TRUE The item is inserted, FALSE otherwise.
3526
3527 @see \ref object_management "Object Management"
3528 */
3529 virtual bool_t insert(int32_t itemIndex, MetaAttribute* attrib) = 0;
3530
3531 /**
3532 Sets a new attribute at the specified index.
3533
3534 @param itemIndex [in] The index in the collection where the new item shall be set.
3535 This must be a valid index in the collection. Indexing starts from 0.
3536
3537 @param attrib [in] A pointer to the MetaAttribute object that shall be set.
3538 It is allowed to set a <b>NULL</b> value to the collection.
3539 Internally the new item is retained (if not <b>NULL</b>), so it is safe to release it
3540 after this method returns. The old item is released (if not <b>NULL</b>).
3541
3542 @return TRUE The item is set, FALSE otherwise.
3543
3544 @see \ref object_management "Object Management"
3545 */
3546 virtual bool_t setAt(int32_t itemIndex, MetaAttribute* attrib) = 0;
3547
3548 /**
3549 Returns whether the object is immutable.
3550 An immmutable object cannot be modified and all modifying methods fail to produce a result.
3551
3552 @return TRUE if the object is immutable, FALSE otherwise.
3553
3554 @remarks
3555 An immutable object <b>can</b> be modified by the AVBlocks library.
3556
3557 @remarks
3558 Object immutability spreads to all nested objects.
3559 Therefore it is not possible to add/set an immutable object to a mutable object.
3560 */
3561 virtual bool_t immutable() const = 0;
3562
3563 protected:
3564
3565 /**
3566 This object can be destroyed only by the library that has created it.
3567
3568 @see primo::Reference::release
3569 */
3570 virtual ~MetaAttributeList() {};
3571 };
3572
3573
3574 /**
3575 Metadata describes meta information that is part of an audio or video file.
3576 It can hold various textual information and images.
3577
3578 @see Library::createMetaAttribute
3579 @see Library::createMetaPicture
3580 @see Library::createMetadata
3581 */
3582 class Metadata : public primo::Reference
3583 {
3584 public:
3585
3586 /**
3587 Creates a deep copy of this object.
3588
3589 @return A new Metadata object.
3590 The caller is responsible for releasing the new object when it is not needed anymore.
3591
3592 @return <b>NULL</b> if there is not enough memory and the object cannot be cloned.
3593
3594 @remarks
3595 When cloned an immutable object becomes mutable.
3596
3597 @see \ref object_management "Object Management"
3598 */
3599 virtual Metadata* clone() const = 0;
3600
3601 /**
3602 Returns a modifiable collection with all the attributes in the Metadata object.
3603
3604 @return A collection of MetaAttribute objects.
3605 The default value is an empty collection which can be modified but it cannot be replaced.
3606
3607 The returned collection exists only in the context of the Metadata object.
3608
3609 @see Library::createMetaAttribute
3610 @see MetaAttributeList
3611 */
3612 virtual MetaAttributeList *attributes() const = 0;
3613
3614 /**
3615 Returns a modifiable collection with all the pictures in the Metadata object.
3616
3617 @return A collection of MetaPicture objects.
3618 The default value is an empty collection which can be modified but it cannot be replaced.
3619
3620 The returned collection exists only in the context of the Metadata object.
3621
3622 @see Library::createMetaPicture
3623 @see MetaPictureList
3624 */
3625 virtual MetaPictureList* pictures() const = 0;
3626
3627 /**
3628 Returns whether the object is immutable.
3629 An immmutable object cannot be modified and all modifying methods fail to produce a result.
3630
3631 @return TRUE if the object is immutable, FALSE otherwise.
3632
3633 @remarks
3634 An immutable object <b>can</b> be modified by the AVBlocks library.
3635
3636 @remarks
3637 Object immutability spreads to all nested objects.
3638 Therefore it is not possible to add/set an immutable object to a mutable object.
3639
3640 @remarks
3641 When cloned an immutable object becomes mutable.
3642 */
3643 virtual bool_t immutable() const = 0;
3644
3645 protected:
3646 /**
3647 This object can be destroyed only by the library that has created it.
3648
3649 @see primo::Reference::release
3650 */
3651 virtual ~Metadata() {};
3652 };
3653
3654
3655
3656 }
3657} // primo::codecs
3658
3659#endif // ___PRIMO_CODECS_AV_H___
3660
3661// Legend:
3662// FR: - future release
3663// TBR: - to be reviewed
3664// .NET: - update .NET version
3665// Java: - update Java version