pex

package module
v4.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 1, 2024 License: MIT Imports: 4 Imported by: 0

README

docs Language

Pex SDK for Golang

Go bindings for the Pex SDK.

Installation

You can install the Go language bindings like this:

go get github.com/Pexeso/pex-sdk-go/v4
Usage examples

You can find usage examples in the examples directory.

Documentation

Overview

Package pex contains the Go bindings for the Pex SDK.

Important! Please make sure to install the core library, as described in the following link: https://docs.search.pex.com/installation/, before trying to use the Go bindings.

Installation

You can install the Go language bindings like this:

go get github.com/Pexeso/pex-sdk-go/v4

Client

Before you can do any operation with the SDK you need to initialize a client.

client, err := pex.NewClient(clientID, clientSecret)
if err != nil {
    panic(err)
}
defer client.Close()

If you want to test the SDK using the mockserver you need to mock the client:

if err := pex.MockClient(client); err != nil {
    panic(err)
}

Fingerprinting

A fingerprint is how the SDK identifies a piece of digital content. It can be generated from a media file or from a memory buffer. The content must be encoded in one of the supported formats and must be longer than 1 second.

You can generate a fingerprint from a media file:

ft, err := client.FingerprintFile("/path/to/file.mp4")
if err != nil {
    panic(err)
}

Or you can generate a fingerprint from a memory buffer:

b, _ := ioutil.ReadFile("/path/to/file.mp4")

ft, err := pex.FingerprintBuffer(b)
if err != nil {
    panic(err)
}

If you only want to use certain types of fingerprinting, you can specify that as well:

ft1, _ := client.FingerprintFileForTypes("/path/to/file.mp4", pex.FingerprintTypeAudio)
ft2, _ := client.FingerprintBufferForTypes(b, pex.FingerprintTypeVideo|pex.FingerprintTypeMelody)

Both the files and the memory buffers must be valid media content in following formats:

Audio: aac
Video: h264, h265

Keep in mind that generating a fingerprint is CPU bound operation and might consume a significant amount of your CPU time.

After the fingerprint is generated, you can use it to perform a metadata search.

// Build the request.
req := &pex.MetadataSearchRequest{
    Fingerprint: ft,
}

// Start the search.
fut, err := client.StartMetadataSearch(req)
if err != nil {
    panic(err)
}

// Do other stuff.

// Retrieve the result.
res, err := fut.Get()
if err != nil {
    panic(err)
}

// Print the result.
fmt.Printf("%+v\n", res)

Performing a license search is very similar to metadata search.

// ...

// Build the request.
req := &pex.LicenseSearchRequest{
    Fingerprint: ft,
}

// Start the search.
fut, err := client.StartLicenseSearch(req)
if err != nil {
    panic(err)
}

// ...

The most significant difference between the searches currently is in the results they return. See MetadataSearchResult and LicenseSearchResult for more information.

Index

Constants

View Source
const (
	StatusOK               = StatusCode(0)
	StatusDeadlineExceeded = StatusCode(1)
	StatusPermissionDenied = StatusCode(2)
	StatusUnauthenticated  = StatusCode(3)
	StatusNotFound         = StatusCode(4)
	StatusInvalidInput     = StatusCode(5)
	StatusOutOfMemory      = StatusCode(6)
	StatusInternalError    = StatusCode(7)
	StatusNotInitialized   = StatusCode(8)
	StatusConnectionError  = StatusCode(9)
	StatusLookupFailed     = StatusCode(10)
	StatusLookupTimedOut   = StatusCode(11)
)
View Source
const (
	// IdentifyMusic is a type of PexSearch that will return results that will
	// help identify the music in the provided media file.
	IdentifyMusic = PexSearchType(C.Pex_SearchType_IdentifyMusic)

	// FindMatches is a type of PexSearch that will return all assets that
	// matched against the given media file.
	FindMatches = PexSearchType(C.Pex_SearchType_FindMatches)
)

Variables

This section is empty.

Functions

func MockClient

func MockClient(c client) error

MockClient initializes the provided client to communicate with the mockserver.

Types

type DSP added in v4.0.1

type DSP struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

type Error

type Error struct {
	Code    StatusCode
	Message string
}

Error will be returend by most SDK functions. Besides an error message, it also includes a status code, which can be used to determine the underlying issue, e.g. AssetLibrary.GetAsset will return an error with StatusNotFound if the asset couldn't be found.

func (*Error) Error

func (e *Error) Error() string

type Fingerprint

type Fingerprint struct {
	// contains filtered or unexported fields
}

Fingerprint is how the SDK identifies a piece of digital content. It can be generated from a media file or from a memory buffer. The content must be encoded in one of the supported formats and must be longer than 1 second.

func NewFingerprint

func NewFingerprint(b []byte) *Fingerprint

func (*Fingerprint) Dump

func (x *Fingerprint) Dump() []byte

type FingerprintType

type FingerprintType int

FingerprintType is a bit flag specifying one or more fingerprint types.

const (
	FingerprintTypeVideo  FingerprintType = 1
	FingerprintTypeAudio  FingerprintType = 2
	FingerprintTypeMelody FingerprintType = 4
	FingerprintTypeAll                    = FingerprintTypeVideo | FingerprintTypeAudio | FingerprintTypeMelody
)

type MatchDetails

type MatchDetails struct {
	Audio  *SegmentDetails `json:"audio"`
	Melody *SegmentDetails `json:"melody"`
	Video  *SegmentDetails `json:"video"`
}

type PexSearchAsset

type PexSearchAsset struct {
	ID string `json:"id"`

	// The title of the asset.
	Title string `json:"title"`

	// The artist who contributed to the asset.
	Artist string `json:"artist"`

	// International Standard Recording Code.
	ISRC string `json:"isrc"`

	// The label that owns the asset (e.g. Sony Music Entertainment).
	Label string `json:"label"`

	// The total duration of the asset in seconds.
	DurationSeconds float32 `json:"duration_seconds"`

	Barcode     string `json:"barcode"`
	Distributor string `json:"distributor"`
	Subtitle    string `json:"subtitle"`
	AlbumName   string `json:"album_name"`
	ReleaseDate struct {
		Year  int `json:"year"`
		Month int `json:"month"`
		Day   int `json:"day"`
	} `json:"release_date"`

	DSP []*DSP `json:"dsp"`
}

type PexSearchClient

type PexSearchClient struct {
	// contains filtered or unexported fields
}

PexSearchClient serves as an entry point to all operations that communicate with Pex backend services. It automatically handles the connection and authentication with the service.

func NewPexSearchClient

func NewPexSearchClient(clientID, clientSecret string) (*PexSearchClient, error)

func (*PexSearchClient) CheckSearch

func (x *PexSearchClient) CheckSearch(lookupIDs []string) (*PexSearchResult, error)

func (*PexSearchClient) Close

func (x *PexSearchClient) Close() error

Close closes all connections to the backend service and releases the memory manually allocated by the core library.

func (*PexSearchClient) FingerprintBuffer

func (x *PexSearchClient) FingerprintBuffer(buffer []byte, types ...FingerprintType) (*Fingerprint, error)

FingerprintBuffer is used to generate a fingerprint from a media file loaded in memory as a byte slice. The types parameter specifies which types of fingerprints to create. If not types are provided, FingerprintTypeAll is assumed.

func (*PexSearchClient) FingerprintFile

func (x *PexSearchClient) FingerprintFile(path string, types ...FingerprintType) (*Fingerprint, error)

FingerprintFile is used to generate a fingerprint from a file stored on a disk. The path parameter must be a path to a valid file in supported format. The types parameter specifies which types of fingerprints to create. If not types are provided, FingerprintTypeAll is assumed.

func (*PexSearchClient) StartSearch

func (x *PexSearchClient) StartSearch(req *PexSearchRequest) (*PexSearchFuture, error)

StartSearch starts a Pex search. This operation does not block until the search is finished, it does however perform a network operation to initiate the search on the backend service.

type PexSearchFuture

type PexSearchFuture struct {
	LookupIDs []string
	// contains filtered or unexported fields
}

PexSearchFuture object is returned by the PexSearchClient.StartSearch function and is used to retrieve a search result.

func (*PexSearchFuture) Get

func (x *PexSearchFuture) Get() (*PexSearchResult, error)

Get blocks until the search result is ready and then returns it. It also releases all the allocated resources, so it will return an error when called multiple times.

type PexSearchMatch

type PexSearchMatch struct {
	// The asset whose fingerprint matches the query.
	Asset *PexSearchAsset `json:"asset"`

	// The matching time segments on the query and asset respectively.
	MatchDetails MatchDetails `json:"match_details"`
}

PexSearchMatch contains detailed information about the match, including information about the matched asset, and the matching segments.

type PexSearchRequest

type PexSearchRequest struct {
	// A fingerprint obtained by calling either NewFingerprintFromFile
	// or NewFingerprintFromBuffer. This field is required.
	Fingerprint *Fingerprint

	// Type is optional and when specified will allow to retrieve results that
	// are more relevant to the given use-case.
	Type PexSearchType
}

Holds all data necessary to perform a pex search. A search can only be performed using a fingerprint, but additional parameters may be supported in the future.

type PexSearchResult

type PexSearchResult struct {
	// IDs that uniquely identify a particular search. Can be used for diagnostics.
	LookupIDs []string `json:"lookup_ids"`

	// The assets which the query matched against.
	Matches []*PexSearchMatch `json:"matches"`

	QueryFileDurationSeconds float32 `json:"query_file_duration_seconds"`
}

This object is returned from PexSearchFuture.Get upon successful completion.

type PexSearchType added in v4.1.0

type PexSearchType int

PexSearchType can optionally be specified in the PexSearchRequest and will allow to retrieve results that are more relevant to the given use-case.

type PrivateSearchClient

type PrivateSearchClient struct {
	// contains filtered or unexported fields
}

PrivateSearchClient serves as an entry point to all operations that communicate with Pex backend services. It automatically handles the connection and authentication with the service.

func NewPrivateSearchClient

func NewPrivateSearchClient(clientID, clientSecret string) (*PrivateSearchClient, error)

func (*PrivateSearchClient) Close

func (x *PrivateSearchClient) Close() error

Close closes all connections to the backend service and releases the memory manually allocated by the core library.

func (*PrivateSearchClient) FingerprintBuffer

func (x *PrivateSearchClient) FingerprintBuffer(buffer []byte, types ...FingerprintType) (*Fingerprint, error)

FingerprintBuffer is used to generate a fingerprint from a media file loaded in memory as a byte slice. The types parameter specifies which types of fingerprints to create. If not types are provided, FingerprintTypeAll is assumed.

func (*PrivateSearchClient) FingerprintFile

func (x *PrivateSearchClient) FingerprintFile(path string, types ...FingerprintType) (*Fingerprint, error)

FingerprintFile is used to generate a fingerprint from a file stored on a disk. The path parameter must be a path to a valid file in supported format. The types parameter specifies which types of fingerprints to create. If not types are provided, FingerprintTypeAll is assumed.

func (*PrivateSearchClient) Ingest

func (x *PrivateSearchClient) Ingest(id string, ft *Fingerprint) error

Ingest ingests a fingerprint into the private search catalog. The catalog is determined from the authentication credentials used when initializing the client. If you want to ingest into multiple catalogs within one application, you need to use multiple clients. The id parameter identifies the fingerprint and will be returned during search to identify the matched asset.

func (*PrivateSearchClient) StartSearch

StartSearch starts a private search. This operation does not block until the search is finished, it does however perform a network operation to initiate the search on the backend service.

type PrivateSearchFuture

type PrivateSearchFuture struct {
	LookupIDs []string
	// contains filtered or unexported fields
}

PrivateSearchFuture object is returned by the Client.StartPrivateSearch function and is used to retrieve a search result.

func (*PrivateSearchFuture) Get

Get blocks until the search result is ready and then returns it. It also releases all the allocated resources, so it will return an error when called multiple times.

type PrivateSearchMatch

type PrivateSearchMatch struct {
	// The ID provided during ingestion.
	ProvidedID string `json:"provided_id"`

	// The matching time segments on the query and asset respectively.
	MatchDetails *MatchDetails `json:"match_details"`
}

PrivateSearchMatch contains detailed information about the match, including information about the matched asset, and the matching segments.

type PrivateSearchRequest

type PrivateSearchRequest struct {
	// A fingerprint obtained by calling either NewFingerprintFromFile
	// or NewFingerprintFromBuffer. This field is required.
	Fingerprint *Fingerprint
}

Holds all data necessary to perform a private search. A search can only be performed using a fingerprint, but additional parameters may be supported in the future.

type PrivateSearchResult

type PrivateSearchResult struct {
	// IDs that uniquely identify a particular search. Can be used for diagnostics.
	LookupIDs []string `json:"lookup_ids"`

	// The assets which the query matched against.
	Matches []*PrivateSearchMatch `json:"matches"`

	QueryFileDurationSeconds float32 `json:"query_file_duration_seconds"`
}

This object is returned from PrivateSearchFuture.Get upon successful completion.

type Segment

type Segment struct {
	// The start of the matched range int the query in seconds (inclusive).
	QueryStart int64 `json:"query_start"`

	// The end of the matched range in the query in seconds (exclusive).
	QueryEnd int64 `json:"query_end"`

	// The start of the matched range in the asset in seconds (inclusive).
	AssetStart int64 `json:"asset_start"`

	// The end of the matched range in the asset in seconds (exclusive).
	AssetEnd int64 `json:"asset_end"`

	AudioPitch          *int64 `json:"audio_pitch"`
	AudioSpeed          *int64 `json:"audio_speed"`
	MelodyTransposition *int64 `json:"melody_transposition"`

	Confidence int64 `json:"confidence"`

	DebugInfo any `json:"debug_info,omitempty"`
}

Segment is the range [start, end) in both the query and the asset of where the match was found within the asset.

type SegmentDetails

type SegmentDetails struct {
	QueryMatchDurationSeconds float32 `json:"query_match_duration_seconds"`
	QueryMatchPercentage      float32 `json:"query_match_percentage"`
	AssetMatchDurationSeconds float32 `json:"asset_match_duration_seconds"`
	AssetMatchPercentage      float32 `json:"asset_match_percentage"`

	Segments []Segment `json:"segments"`
}

type StatusCode

type StatusCode int

StatusCode is used together with Error as a hint on why the error was returned.

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL