Tag Parser: doc/example.cpp Source File

Tag Parser 12.5.2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
example.cpp
Go to the documentation of this file.
1#include <tagparser/abstractattachment.h>
2#include <tagparser/diagnostics.h>
3#include <tagparser/mediafileinfo.h>
4#include <tagparser/progressfeedback.h>
5#include <tagparser/tag.h>
6#include <tagparser/tagvalue.h>
7
12 void example()
13{
14 using namespace std::literals;
15 using namespace TagParser;
16
17 // create a MediaFileInfo for high-level access to overall functionality of the library
18 auto fileInfo = MediaFileInfo();
19
20 // create container for errors, warnings, etc.
21 auto diag = Diagnostics();
22
23 // create handle to abort gracefully and get feedback during long operations
24 auto progress = AbortableProgressFeedback(
25 [](AbortableProgressFeedback &feedback) {
26 // callback for status update
27 std::clog << "At step: " << feedback.step() << '\n';
28 },
29 [](AbortableProgressFeedback &feedback) {
30 // callback for percentage-only updates
31 std::clog << "Step percentage: " << feedback.stepPercentage() << '\n';
32 });
33
34 // open file (might throw ios_base::failure)
35 fileInfo.setPath("/path/to/some/file"sv);
36 fileInfo.open();
37
38 // parse container format, tags, attachments and/or chapters as needed
39 // notes:
40 // - These functions might throw exceptions derived from ios_base::failure for IO errors and
41 // populate diag with potentially critical parsing messages you definitely want to check in production
42 // code.
43 // - Parsing a file can be expensive if the file is large or the disk IO is slow. You might want to
44 // run it in a separate thread.
45 // - At this point the parser does not make much use of the progress object (in contrast to applyChanges()
46 // shown below).
47 fileInfo.parseContainerFormat(diag, progress);
48 fileInfo.parseTags(diag, progress);
49 fileInfo.parseAttachments(diag, progress);
50 fileInfo.parseChapters(diag, progress);
51 fileInfo.parseEverything(diag, progress); // just use that one if you want all of the above
52
53 // get tag as an object derived from the Tag class
54 // notes:
55 // - In real code you might want to check how many tags are assigned or use
56 // fileInfo.createAppropriateTags(...) to create tags as needed.
57 auto tag = fileInfo.tags().at(0);
58
59 // extract a field value and convert it to a UTF-8 std::string (toString() might throw ConversionException)
60 auto title = tag->value(TagParser::KnownField::Title).toString(TagParser::TagTextEncoding::Utf8);
61
62 // change a field value using an encoding suitable for the tag format
63 tag->setValue(KnownField::Album, TagValue("some UTF-8 string", TagTextEncoding::Utf8, tag->proposedTextEncoding()));
64
65 // get/remove/create attachments
66 if (auto *const container = fileInfo.container()) {
67 for (std::size_t i = 0, count = container->attachmentCount(); i != count; ++i) {
68 auto attachment = container->attachment(i);
69 if (attachment->mimeType() == "image/jpeg") {
70 attachment->setIgnored(true); // remove existing attachment
71 }
72 }
73 // create new attachment
74 auto attachment = container->createAttachment();
75 attachment->setName("The cover");
76 attachment->setFile("cover.jpg", diag, progress);
77 }
78
79 // apply changes to the file on disk
80 // notes:
81 // - Might throw exception derived from TagParser::Failure for a fatal processing error or ios_base::failure
82 // for IO errors.
83 // - Applying changes can be expensive if the file is large or the disk IO is slow. You might want to
84 // run it in a separate thread.
85 // - Use progress.tryToAbort() from another thread or an interrupt handler to abort gracefully without leaving
86 // the file in an inconsistent state.
87 // - Ensure everything has been parsed before as the library needs to be aware of the whole file structure.
88 fileInfo.applyChanges(diag, progress);
89}
abstractattachment.h
TagParser::AbortableProgressFeedback
The AbortableProgressFeedback class provides feedback about an ongoing operation via callbacks.
Definition progressfeedback.h:186
TagParser::BasicProgressFeedback::stepPercentage
std::uint8_t stepPercentage() const
Returns the percentage of the current step (initially 0, supposed to be a value from 0 to 100).
Definition progressfeedback.h:77
TagParser::BasicProgressFeedback::step
const std::string & step() const
Returns the name of the current step (initially empty).
Definition progressfeedback.h:68
TagParser::Diagnostics
The Diagnostics class is a container for DiagMessage.
Definition diagnostics.h:156
TagParser::MediaFileInfo
The MediaFileInfo class allows to read and write tag information providing a container/tag format ind...
Definition mediafileinfo.h:83
TagParser::TagValue
The TagValue class wraps values of different types.
Definition tagvalue.h:147
diagnostics.h
example
void example()
An example for reading and writing tags in a format-independent way.
Definition example.cpp:12
mediafileinfo.h
TagParser
Contains all classes and functions of the TagInfo library.
Definition aaccodebook.h:10
TagParser::KnownField::Title
@ Title
Definition tag.h:39
TagParser::KnownField::Album
@ Album
Definition tag.h:40
TagParser::TagTextEncoding::Utf8
@ Utf8
Definition tagvalue.h:31
progressfeedback.h
tag.h
tagvalue.h