Documentation
¶
Overview ¶
Package nzb parses NZB documents: the XML index of a Usenet post that lists every file, its newsgroups and the message IDs of its segments (articles). Besides the raw structure it derives file names from subjects, classifies files (video, archive volumes, par2, extras), flags obfuscated names and groups archive volumes into ordered sets, which is what the stream engine needs to find the playable file of a release.
Index ¶
- Constants
- Variables
- func CleanArchivePath(raw string) string
- func ContentID(data []byte) string
- func ContentSumBytes(data []byte) ([32]byte, bool)
- func FormatContentID(sum [32]byte) string
- func InspectContent(data []byte) (contentID, poster string, uploadDate time.Time, totalBytes int64)
- func IsArchiveMIME(raw string) bool
- func IsNonVideoMIME(raw string) bool
- func IsObfuscated(name string) bool
- func IsPar2Volume(name string) bool
- func IsVideoExt(ext string) bool
- func MIMEFamily(raw string) string
- func MatchPathIndex(names []string, want string) (idx int, found bool, ambiguous bool)
- func MatchTrackIndex(names []string, want TrackHint, mimeFilter string) (idx int, found bool, ambiguous bool)
- func NameFromSubject(subject string) string
- func NonVideoMatchRank(filename, declaredMIME string) int
- func NormalizeMIME(raw string) string
- func ParseContentID(id string) ([32]byte, bool)
- type EpisodeHint
- type File
- type FileInfo
- type Kind
- type MovieHint
- type NZB
- func (n *NZB) ArchiveSets() []*Set
- func (n *NZB) ContentID() string
- func (n *NZB) ContentSum() ([32]byte, bool)
- func (n *NZB) EpisodeHint() (EpisodeHint, bool)
- func (n *NZB) MetaValue(typ string) string
- func (n *NZB) MovieHint() (MovieHint, bool)
- func (n *NZB) NonVideoHint() (NonVideoHint, bool)
- func (n *NZB) Password() string
- func (n *NZB) Subset(keep func(*File) bool) (data []byte, ok bool)
- func (n *NZB) SubsetMeta(keep func(*File) bool, extra map[string]string) (data []byte, ok bool)
- func (n *NZB) TotalBytes() int64
- type NonVideoHint
- type Segment
- type Set
- type TrackHint
Constants ¶
const ContentIDPrefix = "nzb:"
ContentIDPrefix namespaces NZB content identities derived from segment message-IDs.
const MetaEpisode = "ether-episode"
MetaEpisode is the <meta> type that tells the stream engine which episode of a multi-episode archive to play ("season:episode:absolute[,s:e...]").
const MetaMovie = "ether-movie"
MetaMovie carries the requested movie identity and audio language preferences into multi-file NZB and archive member selection.
const MetaNonVideo = "ether-nonvideo"
MetaNonVideo carries non-video release selection intent (explicit posted file, archive member, or media MIME) from a plugin release target into the stream engine.
const MetaSubjectNames = "ether-subject-names"
MetaSubjectNames preserves original subject-derived file names (keyed by 0-based file index in the emitted NZB) when re-encoding rewrites a file's subject to carry a PAR2/yEnc-learned name.
Variables ¶
var ErrInvalid = errors.New("nzb: invalid document")
ErrInvalid is returned for documents that are not usable NZBs.
Functions ¶
func CleanArchivePath ¶
CleanArchivePath normalises a release or archive member path for matching.
func ContentID ¶
ContentID returns "nzb:<sha256>" over the sorted unique segment message-IDs in data, or "" when data is not an NZB document with at least one segment.
func ContentSumBytes ¶
ContentSumBytes parses data as an NZB and returns its 32-byte content digest.
func FormatContentID ¶
FormatContentID formats a 32-byte NZB content digest as "nzb:<64-char lowercase hex>".
func InspectContent ¶
InspectContent extracts the NZB content identity ("nzb:<sha256>" over sorted segment message-IDs) together with the first posted file's poster, UTC upload timestamp, and total listed segment bytes. Non-NZB payloads (such as empty slices or JSON descriptors) return zero values.
func IsArchiveMIME ¶
IsArchiveMIME reports whether raw names a generic wrapper archive format (ZIP, RAR, 7z) rather than a self-contained media format like EPUB or CBZ.
func IsNonVideoMIME ¶
IsNonVideoMIME reports whether raw names a concrete non-video playable media type (audio, ebook, comic, image, or text) suitable for automatic non-video release file selection.
func IsObfuscated ¶
IsObfuscated reports whether a name carries no information about the content: no extension, a hash/UUID-like base, a long random token, or the "abc.xyz" / "b00bs." / "Backup_NNNNNS01-02" placeholders some posters use.
func IsPar2Volume ¶
IsPar2Volume reports whether name is a PAR2 recovery volume ("x.vol03+04.par2") rather than an index file ("x.par2").
func IsVideoExt ¶
IsVideoExt reports whether ext (without dot, any case) is a video container.
func MIMEFamily ¶
MIMEFamily maps a MIME type onto a broad non-video or video media family ("audio", "book", "comic", "image", "text", "video", "archive", or "").
func MatchPathIndex ¶
MatchPathIndex finds the unique index in names matching want by:
- exact normalised path (case-insensitive)
- unique suffix path match (when want contains a slash, e.g. "CD1/01.flac" inside "Album/CD1/01.flac")
- unique basename match (when want has no slash)
It returns (idx, true, false) on a unique match, (-1, false, true) when multiple entries match ambiguously, or (-1, false, false) when none match.
func MatchTrackIndex ¶
func MatchTrackIndex(names []string, want TrackHint, mimeFilter string) (idx int, found bool, ambiguous bool)
MatchTrackIndex finds a unique audio file in names matching want:
- Disc + track number first (disambiguated by normalised title tokens when multiple candidates share a number, failing with ambiguous=true if still not unique).
- Normalised title tokens when no track number was given or no candidate matched by number (contiguous token sequence first, then all tokens present), failing with ambiguous=true when multiple candidates tie.
func NameFromSubject ¶
NameFromSubject extracts the file name from a Usenet subject line, e.g.
`"Movie.2024.part01.rar" yEnc (1/50)` -> Movie.2024.part01.rar `[01/42] - "Movie.2024.mkv" yEnc (1/1000)` -> Movie.2024.mkv `[PRiVATE]-[WtFnZb]-[Movie.2024.mkv]-[1/5] - "" yEnc` -> Movie.2024.mkv `Concert Recording 2019 Full Show.mkv (1/120)` -> Concert Recording 2019 Full Show.mkv `Movie.2024.r00 (1/50)` -> Movie.2024.r00
func NonVideoMatchRank ¶
NonVideoMatchRank scores how well filename matches declaredMIME for automatic non-video release selection:
2 = extension matches the exact declared MIME type 1 = extension belongs to the same non-video media family 0 = not a usable match (wrong family, video, metadata/junk, or no MIME)
func NormalizeMIME ¶
NormalizeMIME strips parameters and normalises ASCII case on a MIME string.
func ParseContentID ¶
ParseContentID decodes an "nzb:<64-char hex>" (or bare 64-char hex) content identity into its 32-byte SHA-256 digest.
Types ¶
type EpisodeHint ¶
EpisodeHint is the wanted episode of a season held inside an archive.
type File ¶
type File struct {
Index int // position in NZB.Files
Poster string
Date time.Time
Subject string
Groups []string
// Segments sorted by Number, de-duplicated: the first occurrence of a
// number wins, later message-IDs for it become its Alternates.
Segments []Segment
// Name is the active file name: initially derived from Subject, and
// potentially updated later from PAR2 or yEnc probing.
Name string
// SubjectName is the original name derived from Subject before any
// PAR2/yEnc rename or re-encoding, preserved across Subset/SubsetMeta.
SubjectName string
// Obfuscated reports that Name looks random (hashes, missing extension),
// so it says nothing about the content.
Obfuscated bool
// Info classifies Name.
Info FileInfo
// SubjectIndex / SubjectCount are the "[03/50]" file counter in the
// subject, 0 when absent. Useful to order obfuscated volumes.
SubjectIndex int
SubjectCount int
// ExpectedSegments is the "(1/N)" segment count in the subject, or 0.
ExpectedSegments int
// Duplicates counts repeated segment numbers folded into an earlier
// segment (as Alternates when the message-ID differs).
Duplicates int
}
File is one posted file.
func Par2Index ¶
Par2Index returns the PAR2 index file among files: the smallest file classified as PAR2 that is not a recovery volume (preferring one that is not a sample's), or nil. The index holds only metadata packets (file names, sizes, hashes), typically a few KB.
func (*File) Bytes ¶
Bytes is the sum of the listed segment sizes. It is the encoded article size, a few percent larger than the decoded file; use it for comparisons.
func (*File) EstimatedDecodedBytes ¶
EstimatedDecodedBytes estimates the decoded payload length from the listed yEnc-encoded segment byte sizes, removing the ~3.1% yEnc escaping and CRLF expansion (1.5625% byte-escaping + 1.5625% line breaks). Callers that rely on this estimate must treat it as approximate rather than exact.
func (*File) Missing ¶
Missing returns the segment numbers in 1..SegmentCount() that the NZB does not list.
func (*File) OriginalName ¶
OriginalName returns the original subject-derived file name before any PAR2/yEnc rename or re-encoding.
func (*File) SegmentCount ¶
SegmentCount is the number of part slots the file has: the highest segment number seen or announced by the subject.
func (*File) StableName ¶
StableName returns a stable selection/listing name for f that does not flip between a readable subject-derived name and a probed PAR2/yEnc name: non-obfuscated files keep their original subject-derived name, while obfuscated files prefer a learned name when known.
type FileInfo ¶
type FileInfo struct {
Kind Kind
// Ext is the lower-cased extension of the content: "mkv" for
// "movie.mkv" and for "movie.mkv.001"; "rar" / "7z" for archives.
Ext string
// Volume is the 0-based position of an archive volume in its set
// (.rar=0, .r00=1, .part01.rar=0, .7z.001=0, .001=0). -1 otherwise.
Volume int
// SetName is the lower-cased name shared by every volume of a set, so
// volumes group by (Kind, SetName). For other files it is the
// lower-cased name without extension.
SetName string
// NewStyle is true for .partNN.rar naming, false for .rar/.rNN.
NewStyle bool
// Sample and Extra flag short clips that are not the feature.
Sample bool
Extra bool
}
FileInfo is what a file name says about a posted file.
type Kind ¶
type Kind int
Kind classifies a posted file by its name.
const ( KindUnknown Kind = iota KindVideo // a playable container (.mkv, .mp4, ...) KindRAR // a RAR volume (.rar, .r00, .partNN.rar) KindSevenZip // a 7z volume (.7z, .7z.001) KindZIP // a ZIP volume (.zip, .zip.001, .z01) KindSplit // a plain split volume (.001, .mkv.001) KindPar2 KindNFO KindSFV KindSubtitle KindImage KindOther // known but irrelevant (.txt, .nzb, .srr, ...) KindISO // a disc image (.iso), played by its main feature )
type MovieHint ¶
type NZB ¶
type NZB struct {
// Meta holds <head><meta type="..."> values by lower-cased type.
Meta map[string][]string
// Files in document order. Files without any valid segment are dropped.
Files []*File
}
NZB is a parsed document.
func ParseReader ¶
ParseReader parses an NZB document from r.
func (*NZB) ArchiveSets ¶
ArchiveSets groups archive volumes by set and orders them. Sets are returned largest first.
func (*NZB) ContentID ¶
ContentID returns "nzb:<sha256>" for the parsed NZB document, or "" if empty.
func (*NZB) ContentSum ¶
ContentSum computes the SHA-256 digest over all sorted unique primary segment message-IDs across every file in doc (each normalized without angle brackets and terminated by '\n'). All files are included so subject de-obfuscation differences across indexers never alter the key.
func (*NZB) EpisodeHint ¶
func (n *NZB) EpisodeHint() (EpisodeHint, bool)
EpisodeHint returns the document's episode hint, if it has a valid one.
func (*NZB) NonVideoHint ¶
func (n *NZB) NonVideoHint() (NonVideoHint, bool)
NonVideoHint returns the document's non-video selection hint, if present.
func (*NZB) Subset ¶
Subset returns the NZB restricted to the files keep accepts, keeping the document metadata (such as the password). Parsing the result gives the same file names, segments and repost alternates as the originals. ok is false when no file is kept.
func (*NZB) SubsetMeta ¶
SubsetMeta is Subset with extra <meta> values added (type -> value). The extra values make the subset a different document, with its own digest.
type NonVideoHint ¶
type NonVideoHint struct {
ExplicitFile bool `json:"explicitFile,omitempty"`
ExactFile string `json:"exactFile,omitempty"`
RawFile bool `json:"rawFile,omitempty"`
Member string `json:"member,omitempty"`
MemberIndex *int `json:"memberIndex,omitempty"`
Track *TrackHint `json:"track,omitempty"`
MIME string `json:"mime,omitempty"`
}
NonVideoHint tells the stream engine to serve a non-video file directly (loose file or archive member) instead of running video-only heuristics.
func (NonVideoHint) String ¶
func (h NonVideoHint) String() string
type Segment ¶
type Segment struct {
Number int // 1-based part number
Bytes int64 // article size as listed in the NZB (encoded, approximate)
MessageID string // without angle brackets
// Alternates are message-IDs of reposts ("fills") of this same part,
// in NZB order, to try when MessageID is missing everywhere. A repost
// carries the same yEnc part, so its bytes must land on the same range.
Alternates []string
}
Segment is one article of a file.
type Set ¶
type Set struct {
Kind Kind
// Name is the lower-cased set name shared by the volumes
// ("movie.2024" for movie.2024.part01.rar, "movie.mkv" for movie.mkv.001).
Name string
// NewStyle is true for .partNN.rar and .z01+.zip sets.
NewStyle bool
// Volumes in order; gaps are listed in Missing. The files' Info is left
// untouched (a part00/.000 set keeps numbering from -1), so grouping the
// same files again gives the same result and concurrent callers do not
// write shared files.
Volumes []*File
// Missing lists absent 0-based volume numbers below the highest present.
Missing []int
// Duplicates are reposted volumes that lost to a larger copy.
Duplicates []*File
}
Set is the ordered volumes of one archive (RAR, 7z, ZIP or plain split).