ptt-go

ptt-go is a Go library for parsing torrent and media filenames to extract structured metadata.

Important

This library is a Go port of dreulavelle/PTT (Python), which was ported from TheBeastLT/parse-torrent-title (JavaScript).

Features

• User-Friendly Interface: Parse torrent titles with a single function call
• Comprehensive Handlers: 250+ regex patterns for quality, codec, audio, languages, etc.
• Anime Detection: 120+ anime release group patterns
• Adult Content Filter: Keyword-based adult content detection
• Highly Extensible: Add custom handlers and transformers

Installation

go get github.com/itsrenoria/ptt-go

Quick Start

package main

import (
    "fmt"
    ptt "github.com/itsrenoria/ptt-go"
)

func main() {
    info := ptt.Parse("The Simpsons S01E01 1080p BluRay x265 HEVC 10bit AAC 5.1 Tigole")
    
    fmt.Println(info.Title)      // "The Simpsons"
    fmt.Println(info.Seasons)    // [1]
    fmt.Println(info.Episodes)   // [1]
    fmt.Println(info.Resolution) // "1080p"
    fmt.Println(info.Quality)    // "BluRay"
    fmt.Println(info.Codec)      // "hevc"
    fmt.Println(info.BitDepth)   // "10bit"
    fmt.Println(info.Audio)      // ["AAC"]
}

Examples

Example 1

Title: The Simpsons S01E01 1080p BluRay x265 HEVC 10bit AAC 5.1 Tigole

Parsed:

{
    "title": "The Simpsons",
    "seasons": [1],
    "episodes": [1],
    "resolution": "1080p",
    "quality": "BluRay",
    "codec": "hevc",
    "bit_depth": "10bit",
    "audio": ["AAC"]
}

Example 2

Title: The.Walking.Dead.S06E07.FRENCH.HDTV.x264-AMB3R.mkv

Parsed:

{
    "title": "The Walking Dead",
    "seasons": [6],
    "episodes": [7],
    "languages": ["fr"],
    "quality": "HDTV",
    "codec": "avc",
    "group": "AMB3R",
    "extension": "mkv"
}

Example 3

Title: Movie.2024.2160p.UHD.BluRay.REMUX.DV.HDR10+.TrueHD.Atmos.7.1-GROUP

Parsed:

{
    "title": "Movie",
    "year": 2024,
    "resolution": "2160p",
    "quality": "BluRay REMUX",
    "hdr": ["DV", "HDR10+"],
    "audio": ["TrueHD", "Atmos"],
    "group": "GROUP"
}

Supported Fields

Field	Type	Description
Title	string	Cleaned media title
Year	int	Release year
Seasons	[]int	Season numbers
Episodes	[]int	Episode numbers
Resolution	string	2160p, 1080p, 720p, 480p
Quality	string	BluRay, WEB-DL, WEBRip, HDRip, etc.
Codec	string	hevc, avc, av1, xvid
Audio	[]string	DTS Lossless, TrueHD, Atmos, AAC, etc.
HDR	[]string	DV, HDR10+, HDR
BitDepth	string	10bit, 8bit
Languages	[]string	ISO 639-1 codes: en, fr, de, etc.
EpisodeCode	string	8-character hash (anime)
Group	string	Release group name
Edition	string	Directors Cut, Extended Edition, IMAX
Network	string	Netflix, Amazon, HBO, Disney
Container	string	mkv, mp4, avi
Extension	string	File extension
Anime	bool	Anime release detected
Adult	bool	Adult content detected
Complete	bool	Complete series/collection
Proper	bool	PROPER release
Repack	bool	REPACK release
Remastered	bool	Remastered release
Documentary	bool	Documentary content
Dubbed	bool	Dubbed audio
Subbed	bool	Contains subtitles
Hardcoded	bool	Hardcoded subtitles
Trash	bool	CAM/TS quality
3D	bool	3D content
Unrated	bool	Unrated version
Upscaled	bool	AI upscaled

Advanced Usage

Create a custom parser instance:

package main

import (
    ptt "github.com/itsrenoria/ptt-go"
)

func main() {
    // Create a new parser
    parser := ptt.NewParser()
    
    // Add default handlers
    ptt.AddDefaults(parser)
    
    // Add custom handler
    parser.AddRegexHandler("custom_field", 
        regexp.MustCompile(`(?i)\bMY_PATTERN\b`),
        ptt.TransformValue("custom_value"),
        ptt.HandlerOptions{Remove: true})
    
    // Parse
    result := parser.Parse("Title with MY_PATTERN 1080p")
}

Built-in Transformers

• TransformNone - Returns matched value unchanged
• TransformValue(v) - Returns static value
• TransformInteger - Converts to integer
• TransformBoolean - Returns true if matched
• TransformLowercase - Lowercases the value
• TransformUppercase - Uppercases the value
• TransformRange - Parses ranges like "1-5" into [1,2,3,4,5]
• TransformArray(fn) - Wraps result in array
• TransformUniqConcat(fn) - Appends unique values to list

Credits

This library is a Go port of:

• dreulavelle/PTT (Python)
• TheBeastLT/parse-torrent-title (JavaScript)

License

MIT License - see LICENSE