Metadata-Version: 2.5
Name: ffmeta
Version: 0.1.0
Summary: Media metadata files -- ffmetadata, Vorbis comments, cue sheets -- read, written and converted through one model
Project-URL: Changelog, https://github.com/veramachine/ffsuite/blob/main/packages/ffmeta/CHANGELOG.md
Project-URL: Homepage, https://github.com/veramachine/ffsuite/tree/main/packages/ffmeta
Project-URL: Issues, https://github.com/veramachine/ffsuite/issues
Project-URL: Repository, https://github.com/veramachine/ffsuite
Author-email: VERA LVX <veralvx@veralvx.com>
Maintainer-email: VERA LVX <veralvx@veralvx.com>
License-Expression: MIT OR Apache-2.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Keywords: chapters,cue,cuesheet,ffmetadata,flac,metadata,opus,tags,vorbis,vorbiscomment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# ffmeta

Media metadata files read, written and converted through one model: FFmpeg's
ffmetadata, Vorbis comments, and cue sheets.

It is pure -- text in, text out: no ffmpeg, no file opened. A file read becomes
one model -- its tags, its streams' tags, its chapters, a cue sheet's disc;
written in another format, what that format cannot hold is told as a note, never
dropped in silence.

| Format         | What it is                                                           |
| -------------- | -------------------------------------------------------------------- |
| ffmetadata     | FFmpeg's `;FFMETADATA1` text: global and stream tags, chapters       |
| Vorbis comment | `NAME=value` lines, as `vorbiscomment` and `metaflac` read and write |
| Cue sheet      | the CDRWIN format: an album's tracks, their times and fields         |

What crosses between them, field by field and with its reasons, is
[ffsuite's mappings skill](https://github.com/veramachine/ffsuite/blob/main/.agents/skills/metadata-mappings/SKILL.md).

## Installing

```sh
pip install ffmeta
```

Python 3.13 or later; the standard library alone.

## Using it

```pycon
>>> import ffmeta
>>> text = ";FFMETADATA1\ntitle=Album\n\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=0\nEND=60000\ntitle=One\n"
>>> meta = ffmeta.read(text, "ffmetadata", "album.ffmeta")
>>> converted = ffmeta.convert(meta, "ffmetadata", "vorbis")
>>> written = ffmeta.write(converted.meta, "vorbis")
>>> print(written.text, end="")
title=Album
CHAPTER000=00:00:00.000
CHAPTER000NAME=One
>>> converted.notes + written.notes
('chapter ends: Vorbis comments hold none (a chapter ends where the next begins): left out',)
>>> ffmeta.read("title=x\n", "ffmetadata", "bad.ffmeta")
Traceback (most recent call last):
  ...
ffmeta.Error: bad.ffmeta:1: not ffmetadata: the first line must begin ;FFMETADATA: title=x
```

What crosses into the target is converted; what does not is a note, from
`convert` (a field the target lacks) or `write` (a structure it lacks). A text
that cannot be read is refused: `ffmeta.Error`, its message the reason.

## Licence

Part of [ffsuite](https://github.com/veramachine/ffsuite), beside ffman: its own package.
Licensed under either of
[MIT](https://github.com/veramachine/ffsuite/blob/main/packages/ffmeta/LICENSE-MIT)
or [Apache-2.0](https://github.com/veramachine/ffsuite/blob/main/packages/ffmeta/LICENSE-APACHE),
at your option.
