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.
Metadata search ¶
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)
License search ¶
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
- func MockClient(c client) error
- type DSP
- type Error
- type Fingerprint
- type FingerprintType
- type MatchDetails
- type PexSearchAsset
- type PexSearchClient
- func (x *PexSearchClient) CheckSearch(lookupIDs []string) (*PexSearchResult, error)
- func (x *PexSearchClient) Close() error
- func (x *PexSearchClient) FingerprintBuffer(buffer []byte, types ...FingerprintType) (*Fingerprint, error)
- func (x *PexSearchClient) FingerprintFile(path string, types ...FingerprintType) (*Fingerprint, error)
- func (x *PexSearchClient) StartSearch(req *PexSearchRequest) (*PexSearchFuture, error)
- type PexSearchFuture
- type PexSearchMatch
- type PexSearchRequest
- type PexSearchResult
- type PexSearchType
- type PrivateSearchClient
- func (x *PrivateSearchClient) Close() error
- func (x *PrivateSearchClient) FingerprintBuffer(buffer []byte, types ...FingerprintType) (*Fingerprint, error)
- func (x *PrivateSearchClient) FingerprintFile(path string, types ...FingerprintType) (*Fingerprint, error)
- func (x *PrivateSearchClient) Ingest(id string, ft *Fingerprint) error
- func (x *PrivateSearchClient) StartSearch(req *PrivateSearchRequest) (*PrivateSearchFuture, error)
- type PrivateSearchFuture
- type PrivateSearchMatch
- type PrivateSearchRequest
- type PrivateSearchResult
- type Segment
- type SegmentDetails
- type StatusCode
Constants ¶
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) )
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 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.
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 ¶
func (x *PrivateSearchClient) StartSearch(req *PrivateSearchRequest) (*PrivateSearchFuture, error)
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 ¶
func (x *PrivateSearchFuture) Get() (*PrivateSearchResult, 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 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.