apavlenko / vmf Goto Github PK

Java bindings for public API need to be created as a part of VMF for use in desktop Java and Android applications.

queryByReference(const std::string& sReferenceName) and queryByReference(const std::string& sReferenceName, const vmf::FieldValue& value) confuse users because of difference between signature and actual functional (reference name vs metadata name)

Fixed in pull request #7

1) MetadataSchema, MetadataDesc, Metadata

• current code:

auto schema = make_shared<MetadataSchema>("schema-name", "author");
VMF_METADATA_BEGIN("channel-name");
    VMF_FIELD_STR("field1");
    VMF_FIELD_INT("field2");
VMF_METADATA_END(schema);
mdStream.addSchema(schema);
auto desc = schema->findMetadataDesc("channel-name");
auto md = std::make_shared<Metadata>(desc);
md->push_back(FieldValue("algo-id", "qqq"));
md->push_back(FieldValue("data", "qqq"));
mdStream.add(md);

• proposed code:

mdStream.addSchema(
    MetadataSchema("schema-name", "author",
        MetadataDesc("channel-name",
            FieldDesc("field1", vmf_string),
            FieldDesc("field2", vmf_integer)
        ),
        MetadataDesc(
            ...
        )
    )
);

mdStream.add(
    Metadata("channel-name",
        FieldValue("field1", "qqq"),
        FieldValue("field2", 10)
    )
);

Less code, no shared_ptr => faster!

A warning "warning C4251: 'XXX' : class 'std::YYY<...>' needs to have dll-interface to be used by clients of class 'XXX'" says that due to several binary-incompatible STL versions on Windows (per VS version) this is dangerous.

All possible VMF code (excluding 3rd-party one, like XMP, libXML2, etc) should be covered by the project tests set; all the uncovered parts should be clearly justified.
The existing automated code coverage infra (https://coveralls.io/github/apavlenko/vmf and https://codecov.io/github/apavlenko/vmf) is recommended for use for this task.

NOTE: the resulting coverage should be 80+%

Requirements:

1. ability to compresses the entire metadata schema on save into media file and de-compress back on load
2. ability to compress and de-compress exported XML/JSON metadata representation (including incremental mode)
3. out-of-box compression algo + API (and a sample) of user-provided algo using open-source compression lib(s) (bz2, gz, lzma)
4. test(s) and sample(s)

class MetadataStream::VideoSegment and convertTimestampToFrameIndex (), convertFrameIndexToTimestamp () methods of MetadataStream class are not documented.

Feature name: Statistics object

Requirements:

• The object coalesces element data from a metadata schema using any of the predefined statistical operations or user-provided code
  • predefined: min, max, average, median, count, sum, last_value
• The object should support 3 update modes:
  • on metadata change (sync/async)
  • on specified time interval (async)
  • by request (sync/async)
• The object should be optionally stored as a part of schema (except user-provided operations)

Note: while any statistic can be easily updated on data addition, some statistics (e.g. MAX or MIN) may require full data re-scan to update on data remove or edit; so the decision is to switch the statistics object to manual (by request) update mode and make full re-scan on explicit request only!

Note: the feature includes API, implementation, tests, samples, doc update

for branches and pull requests
Platforms: win, lin, osx, ios, android + code coverage

    const std::string& sMetadataName,
    const std::vector< FieldDesc >& vFields,
    const std::vector<std::shared_ptr<ReferenceDesc>>& vRefs)

constructor adds empty ReferenceDesc to class field even if it already exists in vRefs.

The Doxygen-generated VMF ref man misses some classes (e.g. FieldValue) that don't have Doxygen comments like:

/*!
* \class Xxx
* \brief %Xxx is a class...
*/

Since MetaString type is a typedef for vmf_string it would be better to remove that type.

The problem appears when disabling return codes in MetadataStream::save() and saveTo() methods (see PR #36).
Test case TestSaveLoadReference.OneToOneReference fails because of incorrect procedure of metadata saving.

In modules/vmdatasource/src/xmpmetadatasource.cpp:118:

xmp->SetStructField(VMF_NS, thisPropertyPath.c_str(), VMF_NS, PROPERTY_SET, nullptr, kXMP_PropValueIsArray);

That string deletes a branch from the syntax tree that XMP keeps internally.

After that the saving procedure writes metadata records, generating paths for them.
In modules/vmdatasource/src/xmpmetadatasource.cpp:137:

    auto it = idMap.find(md->getId());
    if (it == idMap.end())
    {
        xmp->AppendArrayItem(VMF_NS, thisPropertySetPath.c_str(), kXMP_PropValueIsArray, nullptr, kXMP_PropValueIsStruct);
        SXMPUtils::ComposeArrayItemPath(VMF_NS, thisPropertySetPath.c_str(), kXMP_ArrayLastItem, &pathToMetadata);
    }
    else
    {
        pathToMetadata = it->second.path;
    }

Shortly, if there is an existing metadata record then save it using old path in the tree, if there's a new metadata record then append it to the tree.

This code works only if saving old records exactly in the order they were stored in the original file and only after that adding new items.
Metadata removal should be performed separately from that procedure. If it's performed before then all paths are becoming outdated, that is why open/close or SerializeToBuffer/ParseFromBuffer routines should be performed after removal procedure.

Due to some concourse of circumstances in most cases the metadata records are saved in the described order. But in the test case TestSaveLoadReference.OneToOneReference we have a single metadata record that belongs to the description we didn't ask to load (but this record should be loaded because there's a reference pointing on it).
Here we cannot guarantee the order of records and get an exception.

Moreover, here we drop the branch containing the metadata records for the same description that were not loaded. That's why opening and saving such a file will erase them.

The following code produces exception:

std::shared_ptr<vmf::MetadataDesc> desc(new vmf::MetadataDesc(name, type));
std::shared_ptr<vmf::Metadata> metadata(new vmf::Metadata(desc));
metadata->addValue(value);
metadata->getFieldValue("");

where name, type and value are respectively any allowed:

• name of metadata description
• Variant type
• field value

The reason is that creating single-value descriptions is possible, but accessing the (only) field of metadata based on them is impossible. The exception is thrown at the following string:

vmf::Variant Metadata::getFieldValue( const std::string& sName ) const
{
    if( sName.empty() )
    {
        VMF_EXCEPTION(IncorrectParamException, "Field name not specified!");
...

Brief

Users should be able to protected privacy of their metadata.

Requirements

• The following encryption levels needs to be implemented:
  1. the specified field value of the specified metadata record
  2. the entire specified metadata record (except frame/time info)
  3. the specified field values of all the specified metadata channel
  4. the specified metadata channel
  5. the specified metadata schema
  6. the whole metadata
• built-in encryption algo-s based on some popular open-source lib(s) (crypto, crypto++, nettle)
• possibility to use user-provided algo-s

Notes

• Tests, docs and sample(s) is a part of the task
• Java bindings will need to be extended as the feature is done in C++
  (will be submitted as a separate task)

If unique reference already exists, one more called addReference() replaces referenced metadata.