We are developing a macOS application that tags local MP4/M4V movie and TV episode files for playback in the macOS TV app.
We have encountered an intermittent artwork-display issue that we have been unable to explain from the file contents alone.
The observed behavior
The files contain embedded TV metadata and JPEG artwork.
The files play correctly in the TV app.
However, the TV app sometimes displays “No Artwork” for an episode even though the artwork is embedded in the file.
More interestingly, the artwork can subsequently appear without modifying the file at all. For example, closing and reopening the TV app, or changing views, can cause artwork that was previously shown as missing to appear.
This makes it difficult to determine whether the issue is related to the file itself, TV app indexing, or the TV app's metadata/artwork cache.
Controlled experiment
We created nine fresh files from three identical sets of TV episodes:
3 files tagged by our application (Flickis)
3 files tagged by a Python-based tagger
3 files tagged by iFlicks
The same episodes were used across the three sets.
The same artwork was used.
All files were imported into the same macOS TV app environment.
The artwork behavior was intermittent across all three groups.
For example, some files initially displayed artwork and others displayed “No Artwork”. In several cases the artwork appeared later after restarting the TV app, without any modification to the media file.
Container structure
We also extracted the hierarchical atom structure of all nine files, without analysing payloads or attempting to interpret the results.
The three pipelines produce clearly different container structures.
The most notable recurring difference is:
Flickis:
ftyp → moov → mdat
Python tagger:
ftyp → [free] → moov → [free] → mdat
iFlicks:
ftyp → free → mdat → mdat → moov
Thus, the iFlicks files consistently have the moov atom after the media data, whereas Flickis and the Python tagger place moov before mdat.
All three approaches contain embedded artwork (covr) and TV-related metadata.
We are deliberately not assuming that moov placement is the cause. It is simply the most obvious systematic structural difference revealed by the experiment.
What we would like to understand
Does the macOS TV app have specific requirements or expectations regarding the container structure or metadata layout when indexing artwork for local MP4/M4V TV episodes?
In particular:
Does TV.app rely on a particular moov/mdat arrangement when indexing local media?
Are there specific requirements for covr artwork that are not apparent from the public AVFoundation metadata APIs?
Does TV.app impose requirements on the hierarchy or placement of iTunes/QuickTime metadata atoms?
Are free atoms or padding relevant to artwork indexing?
Is artwork indexing performed asynchronously or cached in a way that could explain artwork appearing later without the underlying file changing?
Is there a recommended way to generate local MP4/M4V files that maximizes compatibility with TV.app's artwork indexing?
We are particularly interested in whether there is a documented or recommended container/metadata layout for local TV episodes imported into the macOS TV app, rather than streamed or purchased content.
Any guidance on the expected container structure or the TV app's indexing behavior would be greatly appreciated.
0
0
13