Distribute & Pip¶

Installing PySubler is simple via pip.

$ pip install subler

Get the Code¶

subler is actively developed on GitHub, the code is always available.

You can either clone the public repository:

git clone https://github.com/moogar0880/PySubler.git

Download the tarball:

$ curl -OL https://github.com/moogar0880/PySubler/tarball/master

Or, download the zipball:

$ curl -OL https://github.com/moogar0880/PySubler/zipball/master

Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages by running:

$ python setup.py install

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

>>> 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'

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

>>> 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()

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

Tools Examples¶

Below are some examples of how one might make use of the functions provided within the tools module.

>>> from subler import Subler
>>> from subler.tools import AtomCollection
>>> metadata = AtomCollection()
>>> metadata['TV Show'] = 'Firefly'
>>> metadata['TV Episode #'] = 1
>>> metadata['Genre'] = 'Drama'
>>> s = Subler('/Users/Me/Movies/Firefly/S1/S1E1.m4v', media_kind='TV Show',
...            metadata=metadata.atoms)
>>> s.tag()

>>> from subler.tools import tag_dict
>>> metadata = {'TV Show': 'Firefly', 'TV Episode #': 1, 'Genre': 'Drama'}
>>> tag_dict(metadata, '/Users/Me/Movies/Firefly/S1/S1E1.m4v',
...          media_kind='TV Show')