Skip to main content

Includes:

  • Serato track tag parsing and modification, including cue points, track color, beatgrid, waveform, autogain, etc.
  • Serato library database parsing and modification
  • Serato crate parsing and modification
  • Serato smart crate parsing and rule modification
  • Dynamic beatgrid analysis that can be saved to a track's beatgrid.
  • Serato USB export that beats Serato's sync by putting all files in 1 folder (without duplicates) and only copying changed files, unlike Serato's sync which takes forever and creates many duplicate file locations

Contents

Example uses:

USB:

  • Export crates (including Smart Crates) to USB. Beats Serato's sync by keeping all files in 1 folder and by comparing files for changes (instead of always copying, like Serato does)

Tracks:

  • Change hot cue's text (i.e. change to all caps; change "c" to "CHORUS", etc.)
  • Set a hot cue's text based on its color (i.e. if RED, set to "EXIT")
  • Set a track's color (i.e. if has hot cues, change to BLUE); see Setting track color to set it in the database too
  • Set a piece of metadata due to a track's color (i.e. if track is green, set "grouping" to "TAGGED") (this is useful since can't create smart crates by track color in Serato)
  • Analyze a track's Dynamic Beatgrid and save it to the beatgrid Serato tag.
  • Snap cue points to the nearest beat with a configurable tolerance (e.g. 1/16, 1/8, 1/4 of a beat).

Library:

  • Rename or delete a track file while updating the database, crates, and smart crates as well, so that it doesn't go missing.
  • Set a track's color or beatgrid lock in its tags and the database at once, so Serato shows it right away.

Database:

  • After changing a track's metadata, modify database values for a specific track so that you don't have to "Reload Id3 Tags" in Serato, the change appears in Serato instantly.
  • List the tracks Serato marked corrupt, and why.

Crate:

  • Read a crate's tracks
  • Remove a track from a crate
  • Add a track to a crate
  • List available crates

Smart Crate:

  • Read a smart crate's tracks and rules
  • Modify a smart crate's rules
  • List available smart crates

Installation

Currently designed for Python 3.12+. If you would like backwards compatibility with an older version, please reach out!

pip install serato-tools

That alone covers crates, smart crates, the library database, and USB export. The rest of the features need extra packages, installed through the matching extra:

Extra Install Adds
track_tags pip install "serato-tools[track_tags]" Getting/modifying track metadata: tags, cue points, beatgrid, and waveform (installs mutagen)
waveform_drawing pip install "serato-tools[waveform_drawing]" Viewing a track's waveform (installs mutagen and pillow)
beatgrid_analysis pip install "serato-tools[beatgrid_analysis]" Beatgrid analysis (installs mutagen, librosa, and numpy)
all pip install "serato-tools[all]" Everything above

Examples

Renaming or removing track files across the library

Library changes a track file and every place Serato points to it: the database, crates, and smart crates, so the track isn't left missing in Serato.

It's also the fastest way for an app to work with the library. Each file is parsed only once, the first time it's needed, then kept for every later change, instead of re-parsing the whole library per change. Use library.database for other database changes too (like modifying the database file), so they share that one parse. Keep one Library per library folder, since another copy's save would overwrite this one's changes.

NOTE: Close Serato first. It keeps the library in memory, and saves it over any changes made while it's open.

from serato_tools.library import Library

library = Library()  # or Library("/Volumes/USB/_Serato_") for a library on another drive
library.rename_track_file(
    src="/Users/Username/Music/Dubstep/Raaket - ILL - Original Mix.mp3",
    dest="/Users/Username/Music/Dubstep/Raaket - ILL.mp3",
)
library.remove_track_files(["/Users/Username/Music/Dubstep/Raaket - ILL (Radio Edit).mp3"])  # deletes the files too

Modifying the database file

NOTE: Close Serato first. It keeps the library in memory, and saves it over any changes made while it's open.

import time
from typing import Any

from serato_tools.database_v2 import DatabaseV2

now = int(time.time())
files_set_date = ["/Users/Username/Music/Dubstep/Raaket - ILL.mp3"]

def modify_uadd(filename: str, prev_val: Any):
    print(f'Serato library change - Changed "date added" to today: {filename}')
    return now

def modify_tadd(filename: str, prev_val: Any):
    return str(now)

def remove_group(filename: str, prev_val: Any):
    return " "

db = DatabaseV2()
# the available fields are in DatabaseV2.Fields
db.modify_and_save(
    rules=[
        {"field": DatabaseV2.Fields.DATE_ADDED_U, "files": files_set_date, "func": modify_uadd},
        {"field": DatabaseV2.Fields.DATE_ADDED_T, "files": files_set_date, "func": modify_tadd},
        {"field": DatabaseV2.Fields.GROUPING, "func": remove_group}, # all files
    ]
)

Listing corrupt tracks

>>> python -m serato_tools.database_v2 --list_corrupt
/Users/Username/Music/Dubstep/Raaket - ILL.mp3: Corrupt file: This file contains invalid audio data

Or DatabaseV2().get_corrupt_tracks(), which returns each track's full path with its reason.

Exporting crates to USB

NOTE: replaces existing crates on flash drive! (but does not delete existing track files) (TODO: ability to merge with existing)

>>> serato_usb_export --drive E --crate_matcher "*house*" "*techno*" --root_crate="Dave USB"

On macOS, pass the drive's folder, e.g. --drive /Volumes/USB.

Analyzing and setting a dynamic beatgrid

Rekordbox has Dynamic Beatgrid Analysis but Serato doesn't. This analyzes a non-consistent BPM across a track, such as a track with live drums, and snaps a beatgrid marker to each beat.

NOTE: This feature has only been tested on a couple of tracks. Recommend reviewing the resulting beatgrid in Serato— some grid markers may require adjustment. It seems to be working pretty great though!

>>> serato_analyze_beatgrid "/Users/Username/Music/Dubstep/Raaket - ILL.mp3"

Changing several of a track's tags at once

Track opens the file once and parses its Serato tags; save() then writes all of your changes in a single write, instead of rewriting the whole file once per tag:

from serato_tools.track import Track
from serato_tools.track_cues_v2 import TrackCuesV2

track = Track('/Users/Username/Music/Dubstep/Raaket - ILL.mp3')
track.set_track_color(TrackCuesV2.TrackColors.PURPLE)  # Serato stores it in cues_v2
track.autotags.set(bpm=128)
track.gain.set(gain=-2.5)
track.save()  # one write; returns False, without writing, if nothing changed

Its tags are cues_v2, cues_v1, beatgrid, autotags, waveform, and gain: the same classes as below, so use their own methods to change them, and Track.save() rather than theirs. Each is parsed unless you pass it False, except waveform, which you pass True to parse; a tag that isn't parsed isn't saved either:

track = Track('/Users/Username/Music/Dubstep/Raaket - ILL.mp3', cues_v1=False, beatgrid=False, waveform=True)

Setting track color

Set a track's color, or lock its beatgrid, with Library, which sets it in both the track file's tags and the library database. Serato shows the database, and only reads a file's tags again when the track is loaded or on "Rescan File Tags", so changing only one of the two leaves Serato showing a stale value, or the file losing the change. Close Serato first.

from serato_tools.library import Library
from serato_tools.track_cues_v2 import TrackCuesV2

library = Library()
library.set_db_track_tags(
    '/Users/Username/Music/Dubstep/Raaket - ILL.mp3',
    color=TrackCuesV2.TrackColors.PURPLE,
    beatgrid_locked=True,
    # delete_tags_v1 (the default) deletes the legacy "Serato Markers_" tag, since a stale one stops the new color from appearing in Serato. No issues have been found from deleting it, but use caution with versions of Serato before 3, which may still read it.
    delete_tags_v1=True,
)
# many tracks at once, saving the database only once
library.set_db_tracks_tags({
    '/Users/Username/Music/Dubstep/Raaket - ILL.mp3': {'color': TrackCuesV2.TrackColors.PURPLE},
    '/Users/Username/Music/Dubstep/Other.mp3': {'color': TrackCuesV2.TrackColors.BLUE1, 'beatgrid_locked': False},
})

Only ID3 files (.mp3, .aiff, .aif) are currently supported. A track Serato hasn't analyzed yet gets the color or lock added to its tags, as Serato writes them.

Avoid Track.set_track_color / set_beatgrid_locked (or TrackCuesV2's), or DatabaseV2.modify on the COLOR / BEATGRID_LOCKED fields, on their own, since each changes only one of the two.

Snapping cue positions to the beatgrid

After you have a good beatgrid (including dynamic beatgrids), you can snap cue positions so they land exactly on beats, within a configurable tolerance:

serato_snap_cues_v2 "/Users/Username/Music/Dubstep/Raaket - ILL.mp3" --snap_cues --snap_tolerance 1/16
  • --snap_cues enables snapping for all cue entries in the Serato Markers2 tag.
  • --snap_tolerance is a fraction of a beat (e.g. 1/16, 1/8, 1/4) that a cue point can come within a beat in order to "snap" to it.

Only cue points within the tolerance window of some beat are moved; others are left unchanged.

Modifying track metadata / hot cues

import dataclasses
from mutagen.id3._frames import TIT1
from serato_tools.track_cues_v2 import TrackCuesV2

CueColors = TrackCuesV2.CueColors
TrackColors = TrackCuesV2.TrackColors

tags = TrackCuesV2('/Users/Username/Music/Dubstep/Raaket - ILL.mp3')

def track_rule(track: TrackCuesV2.TrackCuesInfo) -> TrackCuesV2.TrackCuesInfo | None:
    # Set ID3 grouping field from track color
    if track.color is not None:
        track_color = track.color.color
        if track_color == TrackColors.LIMEGREEN3.value:
            tags.tagfile.tags.setall("TIT1", [TIT1(text="TAGGED")])
        elif track_color in [TrackColors.WHITE.value, TrackColors.GREY.value, TrackColors.BLACK.value]:
            tags.tagfile.tags.setall("TIT1", [TIT1(text="UNTAGGED")])

    # Normalize cue colors and names
    new_cues = []
    for c in track.cues:
        # Make "close to red", red.
        cue_color = CueColors.RED.value if c.color in [CueColors.PINKRED.value, CueColors.MAGENTA.value] else c.color
        # Make all cuenames all-caps
        cue_name = c.name.strip().upper()

        new_cues.append(dataclasses.replace(c, color=cue_color, name=cue_name))
    new_track = dataclasses.replace(track, cues=new_cues)
    return new_track if new_track != track else None

tags.modify_entries(track_rule, delete_tags_v1=True)
tags.save()

Listing available crates or smart crates

from serato_tools.crate import Crate
print('\n'.join(Crate.get_crate_files()))

from serato_tools.smart_crate import SmartCrate
print('\n'.join(SmartCrate.get_crate_files()))

Modifying a SmartCrate Rule

via command line

Each rule takes a comparison and a value (or DELETE to remove the rule). The available comparisons are the SmartCrate.RuleComparison names, lowercase: str_contains, str_is, int_is_ge, etc.

one crate

>>> serato_smartcrate '/Users/Username/Music/_Serato_/SmartCrates/Dubstep.scrate' --set_rules --grouping str_is UNTAGGED

all crates

>>> serato_smartcrate --all --set_rules --grouping str_is UNTAGGED

via code

from serato_tools.smart_crate import SmartCrate

crate = SmartCrate('/Users/Username/Music/_Serato_/SmartCrates/Dubstep.scrate')

# updates the rule on this field, or adds the rule if the crate doesn't have one for it.
# the value is stored in the value field the comparison expects, just like Serato does.
crate.set_rule(SmartCrate.RuleField.GROUPING, SmartCrate.RuleComparison.STR_IS, "UNTAGGED")
crate.save()

Crate details and adding a track

from serato_tools.crate import Crate

crate = Crate('/Users/Username/Music/_Serato_/Subcrates/Dubstep.crate')

crate.print_track_paths()
# /Users/Username/Music/Dubstep/Saka - backitup.mp3
# /Users/Username/Music/Dubstep/Mind Splitter - YAPPIN'.mp3
# /Users/Username/Music/Dubstep/Flozone - DO IT.mp3
# /Users/Username/Music/Dubstep/Evalution - Throw It Back.mp3
# ...

print(crate)  # or crate.print()
# vrsn (Version): 1.0/Serato ScratchLive Crate
# osrt (Sorting): [ tvcn (Column Name): key ], [ brev (Reverse Order): False ]
# ovct (Column): [ tvcn (Column Name): song ], [ tvcw (Column Width): 0 ]
# ovct (Column): [ tvcn (Column Name): artist ], [ tvcw (Column Width): 0 ]
# ovct (Column): [ tvcn (Column Name): bpm ], [ tvcw (Column Width): 0 ]
# ovct (Column): [ tvcn (Column Name): playCount ], [ tvcw (Column Width): 0 ]
# otrk (Track): [ ptrk (Track Path): Music/Dubstep/Flozone - Candy Paint.mp3 ]
# otrk (Track): [ ptrk (Track Path): Music/Dubstep/Mind Splitter - LISTEN TO ME.mp3 ]
# otrk (Track): [ ptrk (Track Path): Music/Dubstep/Flozone - DO IT.mp3 ]
# ...


# Example: Add tracks to the crate and save it as a new crate
crate.add_tracks(['/Users/Username/Music/Dubstep/Raaket - ILL.mp3'])
crate.save('/Users/Username/Music/_Serato_/Subcrates/New Crate.crate')

Smart Crate details

from serato_tools.smart_crate import SmartCrate

s_crate = SmartCrate('/Users/Username/Music/_Serato_/SmartCrates/Dubstep.scrate')
print(s_crate)

Track Tags

Original writeup on Serato GEOB tag discoveries: blog post

GEOB Tag Contents Script File
Serato Analysis Serato version information
Serato Autotags BPM and Gain values track_autotags.py
Serato BeatGrid Beatgrid Markers track_beatgrid.py
Serato Markers2 Hotcues, Saved Loops, etc.
(The main one used in newer versions of Serato)
track_cues_v2.py
Serato Markers_ Hotcues, Saved Loops, etc.
(Old, not used in newer versions of Serato)
track_cues_v1.py
Serato Overview Waveform data track_waveform.py
Serato Offsets_ ??? -

What's still unknown in these formats — including the rare, mostly undecoded Serato Offsets_ tag — is collected in docs/MYSTERIES.md.

The different file/tag formats that Serato uses to store the information are documented in docs/fileformats.md, a script to dump the tag data can be found at track_tagdump.py.

Sources

Contributing

If you want a new feature, or have a bug fix, please put in a PR! For anything bigger, or if you're not sure about an approach, feel free to open an issue to discuss it first.

Please contribute here rather than publishing your own fork. One maintained package keeps fixes and format discoveries in one place, instead of splitting them across copies that drift apart.

License

MIT: free to use, modify, and include in your own projects, personal or commercial.

Metadata

Release files for serato-tools 5.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for serato-tools 5.5.0
File Size Uploaded Provenance Actions
serato_tools-5.5.0.tar.gz 73.9 kB With provenance Details for serato_tools-5.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for serato-tools 5.5.0
File Interpreter ABI Platform Actions
serato_tools-5.5.0-py3-none-any.whl Python 3 none any Details for serato_tools-5.5.0-py3-none-any.whl

Total release size: 137.0 kB

Release files / serato_tools-5.5.0.tar.gz

Download URL serato_tools-5.5.0.tar.gz
Size 73.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e1398cc2ec1eced91fdd83ed4e0246ebdc3c673061bb9f81e6735757eeb22242
BLAKE2b-256 checksum
How to use checksums
16604036e13f8019787d1bc45e80692d895cd80a9872573d0d4284cdae6efd82
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / serato_tools-5.5.0-py3-none-any.whl

Download URL serato_tools-5.5.0-py3-none-any.whl
Size 63.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
49df2b8d6e3704e9dbba64157b89626021820ac58a256244b77e15cbb3666684
BLAKE2b-256 checksum
How to use checksums
721dcc7cbe87ad49fa085517cef41e5e80329102f2a027a3fcf9e94001c2d8b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for serato-tools 5.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for serato_tools-5.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

5.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page