subler module¶

This module provides an easily scriptable interface to tagging x264 video format metadata via the SublerCLI.

subler¶

This module provides an easily scriptable interface to tagging an assortment of media types including x264 video, AAC audio, and many others with iTunes formatted metadata via the SublerCLI. By simply creating new metadata Atom‘s and specifying any additionally desired variables in an instance of Subler you can quickly execute the tagging of metadata to a specified file.

class subler.subler.Atom[source]¶

Bases: subler.subler._Atom

A class representing a single metadata atom. It’s important to note that if you attempt to use an invalid tag for this Atom it will not be used when actually tagging the media file via a Subler instance.

data¶: The Subler argument formatted version of this Atom

is_valid()[source]¶: Check that the data in this Atom is valid

class subler.subler.Subler(source, dest=None, chapters=None, delay=None, chapters_preview=False, height=None, language='English', remove=False, optimize=True, downmix=False, rating=None, media_kind='Movie', explicit=None, metadata=None)[source]¶

Bases: object

A Python interface to the SublerCLI that can be used to easily read from and write to a specified source file.

__init__(source, dest=None, chapters=None, delay=None, chapters_preview=False, height=None, language='English', remove=False, optimize=True, downmix=False, rating=None, media_kind='Movie', explicit=None, metadata=None)[source]¶

Create a Subler tagging instance

Parameters:

source – The source file to feed to Subler
dest – The destination file to save any changes to
chapters – A .txt file with chapter information
chapters_preview – Boolean option to create an additional video track with the preview of the chapters. Used by iTunes and some other media clients.
delay – The delay of the subtitle track in ms
height – The pixel height of the subtitle track
language – The language of the subtitle track (i.e. English)
remove – Boolean flag for remove all existing subtitles tracks
optimize – Boolean flag for optimizing the file by moving the moov atom at the begining and interleaving the samples
downmix – downmix audio (mono, stereo, dolby, pl2) from the source file
rating – A valid US, UK, or German content rating
media_kind – The type of media represented by the source file. Valid values are Music, Audiobook, Music Video, Movie, TV Show, Booklet, or Ringtone
explicit – The explicit-ness warning of the content in the source file. Valid values are: None, “Clean”, and “Explicit”
metadata – A list of Atom‘s to be applied to the source file as metadata

existing_metadata¶: Atom representations of the metadata currently contained in the source file

existing_metadata_collection¶: AtomCollection representation of the metadata currently contained in the source file

existing_metadata_raw¶: The metadata currently contained in the source file

explicitness¶: The explicit rating of the content in the source file. Valid explicit ratings are: None, “Clean”, and “Explicit”

media_kind¶: The type of media encapsulated in the source file. Valid values are: Music, Audiobook, Music Video, Movie, TV Show, Booklet, or Ringtone

rating¶: The content rating of the source file. Valid US content ratings are: Not Rated, G, PG, PG-13, R, NC-17, TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA, and Unrated. Valid UK content ratings are: Not Rated, U, Uc, PG, 12, 12A, 15, 18, R18, Exempt, Unrated, and Caution. Valid German content ratings are FSK 0, FSK 6, FSK 12, FSK 16, and FSK 18.

tag()[source]¶: Apply the specified metadata to the source file and output it to the specified destination file

tracks¶: A list of tracks found the source file

version¶: The current version of your systems SublerCLI package

Subler Examples¶

There are many permutations of ways that a user may arrange their metadata, so all of those variations will not be covered here. However, several smaller examples and examples highlighting the additional functionality of this module will be shown below

Basic Information Gathering¶

The subler module can be used to access a variety of information about the specified source file:

>>> from subler import Subler
>>> sub = Subler('/Users/Jon/Movies/Iron Man.m4v')
>>> sub.tracks
['Track: 1, Video Track, 2:06:23:60, 208 kbit/s, H.264, 1280 x 720', 'Track: 2, Stereo, 2:06:23:60, 128 kbit/s, AAC, 2 ch']
>>> sub.existing_metadata
[Atom(tag='Rating', value='PG-13'), Atom(tag='Name', value='Iron Man'),...]
>>> sub.version
'version 0.19'

Although it’s documented above, I’d like to specify that there is a distinct difference between subler.version_info/__version__ and subler.Subler.version.

>>> import subler
>>> subler.version_info
(0, 3, 0)
>>> subler.__version__
'0.3.0'

As shown above, subler.version_info and __version__ depict the version of this Python package, while the subler instances version attribute (seen in the first example) is actually the version information about your systems SublerCLI executable

Tagging an Audio File¶

This example will show how to tag an Audio file with a variety of different types of metadata

>>> from subler import Atom, Subler
>>> atoms = []
>>> artist = Atom('Artist', 'Linkin Park')
>>> album = Atom('Album', 'Hybrid Theory')
>>> track = Atom('Name', 'Papercut')
>>> artwork = Atom('Artwork', '/path/to/artwork.jpg')
>>> metadata = [artist, album, track, artwork]
>>> tagger = Subler('/path/to/papercut.mp3', media_kind='Music',
                    explicit='Explicit', metadata=metadata)
>>> tagger.tag()

Tagging other Media Types¶

Tagging a Audiobook, Music Video, Movie, TV Show, Booklet, or Ringtone is fundamentally no different than an audio file, you just need to remember to explicity set the media_kind attribute for anything that isn’t a Movie.

Valid Tags¶

Also probably worth noting is the list of valid Tag names as the official documentation appears to be out of date:

Name
Artist
Album Artist
Album
Grouping
Composer
Comments
Genre
Release Date
Track
Disk
Tempo
TV Show
TV Episode
TV Network
TV Episode ID
TV Season
Description
Long Description
Series Description
Rating
Studio
Cast
Director
Codirector
Producers
Screenwriters
Lyrics
Copyright
Encoding Tool
Encoded By
Keywords
Category
contentID
artistID
playlistID
genreID
composerID
XID
iTunes Account
iTunes Account Type
iTunes Country
Track Sub- Title
Song Description
Art Director
Arranger
Lyricist
Acknowledgement
Conductor
Linear Notes
Record Company
Original Artist
Phonogram Rights
Producer
Performer
Publisher
Sound Engineer
Soloist
Credits
Thanks
Online Extras
Executive Producer
Sort Name
Sort Artist
Sort Album Artist
Sort Album
Sort Composer
Sort TV Show
Media Kind
HD Video
Gapless
Artwork