1 /* libFLAC++ - Free Lossless Audio Codec library
2 * Copyright (C) 2002 Josh Coalson
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
20 #ifndef FLACPP__METADATA_H
21 #define FLACPP__METADATA_H
25 #include "FLAC/metadata.h"
27 // ===============================================================
29 // Full documentation for the metadata interface can be found
30 // in the C layer in include/FLAC/metadata.h
32 // ===============================================================
34 /** \file include/FLAC++/metadata.h
37 * This module provides classes for creating and manipulating FLAC
38 * metadata blocks in memory, and three progressively more powerful
39 * interfaces for traversing and editing metadata in FLAC files.
41 * See the detailed documentation for each interface in the
42 * \link flacpp_metadata metadata \endlink module.
45 /** \defgroup flacpp_metadata FLAC++/metadata.h: metadata interfaces
49 * This module provides classes for creating and manipulating FLAC
50 * metadata blocks in memory, and three progressively more powerful
51 * interfaces for traversing and editing metadata in FLAC files.
53 * The behavior closely mimics the C layer interface; be sure to read
54 * the detailed description of the
55 * \link flac_metadata C metadata module \endlink.
62 // ============================================================
66 // ============================================================
68 /** \defgroup flacpp_metadata_object FLAC++/metadata.h: metadata object classes
69 * \ingroup flacpp_metadata
71 * This module contains classes representing FLAC metadata
74 * The behavior closely mimics the C layer interface; be
75 * sure to read the detailed description of the
76 * \link flac_metadata_object C metadata object module \endlink.
78 * Any time a metadata object is constructed or assigned, you
79 * should check is_valid() to make sure the underlying
80 * ::FLAC__StreamMetadata object was able to be created.
83 * When the get_*() methods of any metadata object method
84 * return you a const pointer, DO NOT disobey and write into it.
85 * Always use the set_*() methods.
90 /** Base class for all metadata block types.
92 class FLACPP_API Prototype {
95 /** Constructs a copy of the given object. This form
96 * always performs a deep copy.
98 Prototype(const Prototype &);
99 Prototype(const ::FLAC__StreamMetadata &);
100 Prototype(const ::FLAC__StreamMetadata *);
103 /** Constructs an object with copy control. When \a copy
104 * is \c true, behaves identically to
105 * FLAC::Metadata::Prototype::Prototype(const ::FLAC__StreamMetadata *object).
106 * When \a copy is \c false, the instance takes ownership of
107 * the pointer and the ::FLAC__StreamMetadata object will
108 * be freed by the destructor.
111 * \code object != NULL \endcode
113 Prototype(::FLAC__StreamMetadata *object, bool copy);
116 /** Assign from another object. Always performs a deep copy. */
117 void operator=(const Prototype &);
118 void operator=(const ::FLAC__StreamMetadata &);
119 void operator=(const ::FLAC__StreamMetadata *);
122 /** Deletes the underlying ::FLAC__StreamMetadata object.
124 virtual void clear();
126 ::FLAC__StreamMetadata *object_;
128 /** Deletes the underlying ::FLAC__StreamMetadata object.
130 virtual ~Prototype();
133 /** Check for equality, performing a deep compare by following pointers. */
134 inline bool operator==(const Prototype &) const;
135 inline bool operator==(const ::FLAC__StreamMetadata &) const;
136 inline bool operator==(const ::FLAC__StreamMetadata *) const;
140 /** Check for inequality, performing a deep compare by following pointers. */
141 inline bool operator!=(const Prototype &) const;
142 inline bool operator!=(const ::FLAC__StreamMetadata &) const;
143 inline bool operator!=(const ::FLAC__StreamMetadata *) const;
146 friend class SimpleIterator;
147 friend class Iterator;
149 /** Returns \c true if the object was correctly constructed
150 * (i.e. the underlying ::FLAC__StreamMetadata object was
151 * properly allocated), else \c false.
153 inline bool is_valid() const;
155 /** Returns \c true if this block is the last block in a
156 * stream, else \c false.
159 * \code is_valid() \endcode
161 bool get_is_last() const;
163 /** Returns the type of the block.
166 * \code is_valid() \endcode
168 ::FLAC__MetadataType get_type() const;
170 /** Returns the stream length of the metadata block.
173 * The length does not include the metadata block header,
177 * \code is_valid() \endcode
179 unsigned get_length() const;
181 /** Sets the "is_last" flag for the block. When using the iterators
182 * it is not necessary to set this flag; they will do it for you.
185 * \code is_valid() \endcode
187 void set_is_last(bool);
189 /** Private and undefined so you can't use it. */
192 // These are used only by Iterator
194 inline void set_reference(bool x) { is_reference_ = x; }
197 inline bool Prototype::operator==(const Prototype &object) const
198 { return (bool)::FLAC__metadata_object_is_equal(object_, object.object_); }
200 inline bool Prototype::operator==(const ::FLAC__StreamMetadata &object) const
201 { return (bool)::FLAC__metadata_object_is_equal(object_, &object); }
203 inline bool Prototype::operator==(const ::FLAC__StreamMetadata *object) const
204 { return (bool)::FLAC__metadata_object_is_equal(object_, object); }
206 inline bool Prototype::operator!=(const Prototype &object) const
207 { return !operator==(object); }
209 inline bool Prototype::operator!=(const ::FLAC__StreamMetadata &object) const
210 { return !operator==(object); }
212 inline bool Prototype::operator!=(const ::FLAC__StreamMetadata *object) const
213 { return !operator==(object); }
215 inline bool Prototype::is_valid() const
216 { return 0 != object_; }
218 /** Create a deep copy of an object and return it. */
219 FLACPP_API Prototype *clone(const Prototype *);
222 /** STREAMINFO metadata block.
223 * See <A HREF="../format.html#metadata_block_streaminfo">format specification</A>.
225 class FLACPP_API StreamInfo : public Prototype {
230 /** Constructs a copy of the given object. This form
231 * always performs a deep copy.
233 inline StreamInfo(const StreamInfo &object): Prototype(object) { }
234 inline StreamInfo(const ::FLAC__StreamMetadata &object): Prototype(object) { }
235 inline StreamInfo(const ::FLAC__StreamMetadata *object): Prototype(object) { }
238 /** Constructs an object with copy control. See
239 * Prototype(::FLAC__StreamMetadata *object, bool copy).
241 inline StreamInfo(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
246 /** Assign from another object. Always performs a deep copy. */
247 inline void operator=(const StreamInfo &object) { Prototype::operator=(object); }
248 inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
249 inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
253 /** Check for equality, performing a deep compare by following pointers. */
254 inline bool operator==(const StreamInfo &object) const { return Prototype::operator==(object); }
255 inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
256 inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
260 /** Check for inequality, performing a deep compare by following pointers. */
261 inline bool operator!=(const StreamInfo &object) const { return Prototype::operator!=(object); }
262 inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
263 inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
267 /** See <A HREF="../format.html#metadata_block_streaminfo">format specification</A>. */
268 unsigned get_min_blocksize() const;
269 unsigned get_max_blocksize() const;
270 unsigned get_min_framesize() const;
271 unsigned get_max_framesize() const;
272 unsigned get_sample_rate() const;
273 unsigned get_channels() const;
274 unsigned get_bits_per_sample() const;
275 FLAC__uint64 get_total_samples() const;
276 const FLAC__byte *get_md5sum() const;
278 void set_min_blocksize(unsigned value);
279 void set_max_blocksize(unsigned value);
280 void set_min_framesize(unsigned value);
281 void set_max_framesize(unsigned value);
282 void set_sample_rate(unsigned value);
283 void set_channels(unsigned value);
284 void set_bits_per_sample(unsigned value);
285 void set_total_samples(FLAC__uint64 value);
286 void set_md5sum(const FLAC__byte value[16]);
290 /** PADDING metadata block.
291 * See <A HREF="../format.html#metadata_block_padding">format specification</A>.
293 class FLACPP_API Padding : public Prototype {
298 /** Constructs a copy of the given object. This form
299 * always performs a deep copy.
301 inline Padding(const Padding &object): Prototype(object) { }
302 inline Padding(const ::FLAC__StreamMetadata &object): Prototype(object) { }
303 inline Padding(const ::FLAC__StreamMetadata *object): Prototype(object) { }
306 /** Constructs an object with copy control. See
307 * Prototype(::FLAC__StreamMetadata *object, bool copy).
309 inline Padding(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
314 /** Assign from another object. Always performs a deep copy. */
315 inline void operator=(const Padding &object) { Prototype::operator=(object); }
316 inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
317 inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
321 /** Check for equality, performing a deep compare by following pointers. */
322 inline bool operator==(const Padding &object) const { return Prototype::operator==(object); }
323 inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
324 inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
328 /** Check for inequality, performing a deep compare by following pointers. */
329 inline bool operator!=(const Padding &object) const { return Prototype::operator!=(object); }
330 inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
331 inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
334 void set_length(unsigned length);
337 /** APPLICATION metadata block.
338 * See <A HREF="../format.html#metadata_block_application">format specification</A>.
340 class FLACPP_API Application : public Prototype {
345 /** Constructs a copy of the given object. This form
346 * always performs a deep copy.
348 inline Application(const Application &object): Prototype(object) { }
349 inline Application(const ::FLAC__StreamMetadata &object): Prototype(object) { }
350 inline Application(const ::FLAC__StreamMetadata *object): Prototype(object) { }
353 /** Constructs an object with copy control. See
354 * Prototype(::FLAC__StreamMetadata *object, bool copy).
356 inline Application(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
361 /** Assign from another object. Always performs a deep copy. */
362 inline void operator=(const Application &object) { Prototype::operator=(object); }
363 inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
364 inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
368 /** Check for equality, performing a deep compare by following pointers. */
369 inline bool operator==(const Application &object) const { return Prototype::operator==(object); }
370 inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
371 inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
375 /** Check for inequality, performing a deep compare by following pointers. */
376 inline bool operator!=(const Application &object) const { return Prototype::operator!=(object); }
377 inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
378 inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
381 const FLAC__byte *get_id() const;
382 const FLAC__byte *get_data() const;
384 void set_id(const FLAC__byte value[4]);
385 //! This form always copies \a data
386 bool set_data(const FLAC__byte *data, unsigned length);
387 bool set_data(FLAC__byte *data, unsigned length, bool copy);
390 /** SEEKTABLE metadata block.
391 * See <A HREF="../format.html#metadata_block_seektable">format specification</A>.
393 class FLACPP_API SeekTable : public Prototype {
398 /** Constructs a copy of the given object. This form
399 * always performs a deep copy.
401 inline SeekTable(const SeekTable &object): Prototype(object) { }
402 inline SeekTable(const ::FLAC__StreamMetadata &object): Prototype(object) { }
403 inline SeekTable(const ::FLAC__StreamMetadata *object): Prototype(object) { }
406 /** Constructs an object with copy control. See
407 * Prototype(::FLAC__StreamMetadata *object, bool copy).
409 inline SeekTable(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
414 /** Assign from another object. Always performs a deep copy. */
415 inline void operator=(const SeekTable &object) { Prototype::operator=(object); }
416 inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
417 inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
421 /** Check for equality, performing a deep compare by following pointers. */
422 inline bool operator==(const SeekTable &object) const { return Prototype::operator==(object); }
423 inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
424 inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
428 /** Check for inequality, performing a deep compare by following pointers. */
429 inline bool operator!=(const SeekTable &object) const { return Prototype::operator!=(object); }
430 inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
431 inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
434 unsigned get_num_points() const;
435 ::FLAC__StreamMetadata_SeekPoint get_point(unsigned index) const;
437 //! See FLAC__metadata_object_seektable_set_point()
438 void set_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
440 //! See FLAC__metadata_object_seektable_insert_point()
441 bool insert_point(unsigned index, const ::FLAC__StreamMetadata_SeekPoint &point);
443 //! See FLAC__metadata_object_seektable_delete_point()
444 bool delete_point(unsigned index);
446 //! See FLAC__metadata_object_seektable_is_legal()
447 bool is_legal() const;
450 /** VORBIS_COMMENT metadata block.
451 * See <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>.
453 class FLACPP_API VorbisComment : public Prototype {
455 /** Convenience class for encapsulating Vorbis comment
456 * entries. An entry is a vendor string or a comment
457 * field. In the case of a vendor string, the field
458 * name is undefined; only the field value is relevant.
460 * A \a field as used in the methods refers to an
461 * entire 'NAME=VALUE' string; the string is not null-
462 * terminated and a length field is required since the
463 * string may contain embedded nulls.
465 * A \a field_name is what is on the left side of the
466 * first '=' in the \a field. By definition it is ASCII
467 * and so is null-terminated and does not require a
468 * length to describe it. \a field_name is undefined
469 * for a vendor string entry.
471 * A \a field_value is what is on the right side of the
472 * first '=' in the \a field. By definition, this may
473 * contain embedded nulls and so a \a field_value_length
474 * is requires to describe it.
476 * Always check is_valid() after the constructor or operator=
477 * to make sure memory was properly allocated.
479 class FLACPP_API Entry {
482 Entry(const char *field, unsigned field_length);
483 Entry(const char *field_name, const char *field_value, unsigned field_value_length);
484 Entry(const Entry &entry);
485 void operator=(const Entry &entry);
489 virtual bool is_valid() const;
491 unsigned get_field_length() const;
492 unsigned get_field_name_length() const;
493 unsigned get_field_value_length() const;
495 ::FLAC__StreamMetadata_VorbisComment_Entry get_entry() const;
496 const char *get_field() const;
497 const char *get_field_name() const;
498 const char *get_field_value() const;
500 bool set_field(const char *field, unsigned field_length);
501 bool set_field_name(const char *field_name);
502 bool set_field_value(const char *field_value, unsigned field_value_length);
505 ::FLAC__StreamMetadata_VorbisComment_Entry entry_;
507 unsigned field_name_length_;
509 unsigned field_value_length_;
514 void clear_field_name();
515 void clear_field_value();
516 void construct(const char *field, unsigned field_length);
517 void construct(const char *field_name, const char *field_value, unsigned field_value_length);
518 void compose_field();
525 /** Constructs a copy of the given object. This form
526 * always performs a deep copy.
528 inline VorbisComment(const VorbisComment &object): Prototype(object) { }
529 inline VorbisComment(const ::FLAC__StreamMetadata &object): Prototype(object) { }
530 inline VorbisComment(const ::FLAC__StreamMetadata *object): Prototype(object) { }
533 /** Constructs an object with copy control. See
534 * Prototype(::FLAC__StreamMetadata *object, bool copy).
536 inline VorbisComment(::FLAC__StreamMetadata *object, bool copy): Prototype(object, copy) { }
541 /** Assign from another object. Always performs a deep copy. */
542 inline void operator=(const VorbisComment &object) { Prototype::operator=(object); }
543 inline void operator=(const ::FLAC__StreamMetadata &object) { Prototype::operator=(object); }
544 inline void operator=(const ::FLAC__StreamMetadata *object) { Prototype::operator=(object); }
548 /** Check for equality, performing a deep compare by following pointers. */
549 inline bool operator==(const VorbisComment &object) const { return Prototype::operator==(object); }
550 inline bool operator==(const ::FLAC__StreamMetadata &object) const { return Prototype::operator==(object); }
551 inline bool operator==(const ::FLAC__StreamMetadata *object) const { return Prototype::operator==(object); }
555 /** Check for inequality, performing a deep compare by following pointers. */
556 inline bool operator!=(const VorbisComment &object) const { return Prototype::operator!=(object); }
557 inline bool operator!=(const ::FLAC__StreamMetadata &object) const { return Prototype::operator!=(object); }
558 inline bool operator!=(const ::FLAC__StreamMetadata *object) const { return Prototype::operator!=(object); }
561 unsigned get_num_comments() const;
562 Entry get_vendor_string() const; // only the Entry's field name should be used
563 Entry get_comment(unsigned index) const;
565 //! See FLAC__metadata_object_vorbiscomment_set_vendor_string()
566 //! \note Only the Entry's field name will be used.
567 bool set_vendor_string(const Entry &entry); // only the Entry's field name will be used
569 //! See FLAC__metadata_object_vorbiscomment_set_comment()
570 bool set_comment(unsigned index, const Entry &entry);
572 //! See FLAC__metadata_object_vorbiscomment_insert_comment()
573 bool insert_comment(unsigned index, const Entry &entry);
575 //! See FLAC__metadata_object_vorbiscomment_delete_comment()
576 bool delete_comment(unsigned index);
582 /** \defgroup flacpp_metadata_level0 FLAC++/metadata.h: metadata level 0 interface
583 * \ingroup flacpp_metadata
586 * Level 0 metadata iterator.
588 * See the \link flac_metadata_level0 C layer equivalent \endlink
594 //! See FLAC__metadata_get_streaminfo().
595 FLACPP_API bool get_streaminfo(const char *filename, StreamInfo &streaminfo);
600 /** \defgroup flacpp_metadata_level1 FLAC++/metadata.h: metadata level 1 interface
601 * \ingroup flacpp_metadata
604 * Level 1 metadata iterator.
606 * The flow through the iterator in the C++ layer is similar
608 * - Create a SimpleIterator instance
609 * - Check SimpleIterator::is_valid()
610 * - Call SimpleIterator::init() and check the return
611 * - Traverse and/or edit. Edits are written to file
613 * - Destroy the SimpleIterator instance
615 * The ownership of pointers in the C++ layer follows that in
617 * - The objects returned by get_block() are yours to
618 * modify, but changes are not reflected in the FLAC file
619 * until you call set_block(). The objects are also
620 * yours to delete; they are not automatically deleted
621 * when passed to set_block() or insert_block_after().
623 * See the \link flac_metadata_level1 C layer equivalent \endlink
629 /** This class is a wrapper around the FLAC__metadata_simple_iterator
630 * structures and methods; see ::FLAC__Metadata_SimpleIterator.
632 class FLACPP_API SimpleIterator {
634 class FLACPP_API Status {
636 inline Status(::FLAC__Metadata_SimpleIteratorStatus status): status_(status) { }
637 inline operator ::FLAC__Metadata_SimpleIteratorStatus() const { return status_; }
638 inline const char *as_cstring() const { return ::FLAC__Metadata_SimpleIteratorStatusString[status_]; }
640 ::FLAC__Metadata_SimpleIteratorStatus status_;
644 virtual ~SimpleIterator();
646 bool init(const char *filename, bool read_only, bool preserve_file_stats);
648 bool is_valid() const;
650 bool is_writable() const;
655 ::FLAC__MetadataType get_block_type() const;
656 Prototype *get_block();
657 bool set_block(Prototype *block, bool use_padding = true);
658 bool insert_block_after(Prototype *block, bool use_padding = true);
659 bool delete_block(bool use_padding = true);
662 ::FLAC__Metadata_SimpleIterator *iterator_;
669 /** \defgroup flacpp_metadata_level2 FLAC++/metadata.h: metadata level 2 interface
670 * \ingroup flacpp_metadata
673 * Level 2 metadata iterator.
675 * The flow through the iterator in the C++ layer is similar
677 * - Create a Chain instance
678 * - Check Chain::is_valid()
679 * - Call Chain::read() and check the return
680 * - Traverse and/or edit with an Iterator or with
681 * Chain::merge_padding() or Chain::sort_padding()
682 * - Write changes back to FLAC file with Chain::write()
683 * - Destroy the Chain instance
685 * The ownership of pointers in the C++ layer follows that in
687 * - The objects returned by Iterator::get_block() are
688 * owned by the iterator and should not be deleted.
689 * When you modify the block, you are directly editing
690 * what's in the chain and do not need to call
691 * Iterator::set_block(). However the changes will not
692 * be reflected in the FLAC file until the chain is
693 * written with Chain::write().
694 * - When you pass an object to Iterator::set_block(),
695 * Iterator::insert_block_before(), or
696 * Iterator::insert_block_after(), the iterator takes
697 * ownership of the block and it will be deleted with the
700 * See the \link flac_metadata_level2 C layer equivalent \endlink
706 /** This class is a wrapper around the FLAC__metadata_chain
707 * structures and methods; see ::FLAC__Metadata_Chain.
709 class FLACPP_API Chain {
711 class FLACPP_API Status {
713 inline Status(::FLAC__Metadata_ChainStatus status): status_(status) { }
714 inline operator ::FLAC__Metadata_ChainStatus() const { return status_; }
715 inline const char *as_cstring() const { return ::FLAC__Metadata_ChainStatusString[status_]; }
717 ::FLAC__Metadata_ChainStatus status_;
723 friend class Iterator;
725 bool is_valid() const;
728 bool read(const char *filename);
729 bool write(bool use_padding = true, bool preserve_file_stats = false);
731 void merge_padding();
735 ::FLAC__Metadata_Chain *chain_;
736 virtual void clear();
739 /** This class is a wrapper around the FLAC__metadata_iterator
740 * structures and methods; see ::FLAC__Metadata_Iterator.
742 class FLACPP_API Iterator {
747 bool is_valid() const;
749 void init(Chain &chain);
754 ::FLAC__MetadataType get_block_type() const;
755 Prototype *get_block();
756 bool set_block(Prototype *block);
757 bool delete_block(bool replace_with_padding);
758 bool insert_block_before(Prototype *block);
759 bool insert_block_after(Prototype *block);
762 ::FLAC__Metadata_Iterator *iterator_;
763 virtual void clear();