Class: Audd::RecognizeRequest

Inherits:
Object
  • Object
show all
Defined in:
lib/audd/recognize_request.rb

Overview

Chainable builder for POST api.audd.io/. Built by Audd::Client#recognize; nothing is sent until #execute!.

audd.recognize(file: "clip.mp3")
  .return_metadata(:apple_music, :spotify)
  .market("us")
  .execute!

Constant Summary collapse

RETURN_METADATA_SOURCES = 
%w[apple_music spotify deezer musicbrainz].freeze
DEFAULT_TIMEOUT =

The server holds the connection open while it fingerprints the audio, so this is generous by HTTP standards.

60

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:, file: nil, url: nil, timeout: DEFAULT_TIMEOUT) ⇒ RecognizeRequest

Returns a new instance of RecognizeRequest.



25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/audd/recognize_request.rb', line 25

def initialize(client:, file: nil, url: nil, timeout: DEFAULT_TIMEOUT)
  if file.nil? == url.nil?
    raise InvalidParameterError,
      "recognize requires exactly one of file: or url:, got " \
      "#{file.nil? ? "neither" : "both"}."
  end

  @client = client
  @file = file
  @url = url
  @timeout = timeout
  @return_metadata = []
  @market = nil
end

Instance Attribute Details

#file ⇒ Object (readonly)

Returns the value of attribute file.



23
24
25
 
# File 'lib/audd/recognize_request.rb', line 23

def file
  @file
end

#url ⇒ Object (readonly)

Returns the value of attribute url.



23
24
25
 
# File 'lib/audd/recognize_request.rb', line 23

def url
  @url
end

Instance Method Details

#execute! ⇒ Audd::RecognitionResult?

Sends the request.

Returns:

  • (Audd::RecognitionResult, nil) —

    nil when the audio was processed but nothing matched — a successful response, not an error.



72
73
74
75
76
77
78
79
 
# File 'lib/audd/recognize_request.rb', line 72

def execute!
  body = Source.with_file(@file) do |file_part|
    response = @client.post("/", fields: form_fields, timeout: @timeout, file: file_part)
    ResponseParser.decode!(response)
  end

  RecognizeSuccessResponse.new(body).result
end

#form_fields ⇒ Object

The multipart fields this request will send, minus the api_token the client adds.



83
84
85
86
87
88
89
 
# File 'lib/audd/recognize_request.rb', line 83

def form_fields
  fields = {}
  fields["url"] = @url if @url
  fields["return"] = @return_metadata.join(",") unless @return_metadata.empty?
  fields["market"] = @market if @market
  fields
end

#market(code) ⇒ Object

ISO country code for the regional Apple Music / Spotify catalogs.



57
58
59
60
 
# File 'lib/audd/recognize_request.rb', line 57

def market(code)
  @market = code.to_s
  self
end

#return_metadata(*sources) ⇒ Object

Extra metadata to fetch for the match, e.g. :apple_music, :spotify. Repeated calls accumulate.



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/audd/recognize_request.rb', line 42

def return_metadata(*sources)
  sources = sources.flatten.map(&:to_s)
  unknown = sources - RETURN_METADATA_SOURCES

  unless unknown.empty?
    raise InvalidParameterError,
      "unknown return_metadata source(s): #{unknown.join(", ")}. " \
      "Valid sources: #{RETURN_METADATA_SOURCES.join(", ")}."
  end

  @return_metadata |= sources
  self
end

#timeout(seconds) ⇒ Object

Overrides DEFAULT_TIMEOUT for this request, in seconds.



63
64
65
66
 
# File 'lib/audd/recognize_request.rb', line 63

def timeout(seconds)
  @timeout = seconds
  self
end