SpeechToText.recognize should have an overload that takes an AudioInputStream

[candrews]

SpeechToText.recognize can currently only be used with a File - this means that using the current API, totally in-memory operation isn't possible.

Can a method with this signature be added?

public com.ibm.watson.developer_cloud.speech_to_text.v1.model.SpeechResults com.ibm.watson.developer_cloud.speech_to_text.v1.SpeechToText.recognize(javax.sound.sampled.AudioInputStream ais, java.util.Map<String, Object> params)

Also, AudioInputStream.getFormat can be used to get the format, so the caller of this method need not specify the CONTENT_TYPE entry in the params map.

[germanattanasio]

We can add that functionality to

public SpeechResults SpeechToText.recognize(Map<String, Object> params)

I don't think we need another method. In fact the idea of having a Map is that we can add parameters without changing the method signature.

Let me see what I can do with javax.sound.sampled.AudioInputStream ais. You won't get interim results that's for sure.

[candrews]

I recommend against simply adding it to the existing map method. Technically, any function in Java be defined as:

public Object doStuff(Map<String, Object> params)

with doStuff having a whole lot of if statements. I think we all agree that would be bad design :-)

By using appropriately named methods with appropriate parameters, you get the benefits of strong typing, self-documentation, separation of concerns, and other general good design features. Please don't just implement everything in one God-method - use separate methods as programming language creators intended.

[germanattanasio]

The problem is when you have a method that can receive 20 arguments and some of them are null.
We used to do what you are describing and we found that users were doing things like

service.doStuff(null,null,null,3,null,"batman",null);

We found that stripe does something similar with their sdk. https://stripe.com/docs/api/java#create_charge

Now imagine how hard it's to document the api if we have 20 java method for one simple API call

[candrews]

There's always a happy medium, and I think stripe hits it with their SDK too.
There are currently these methods:

public SpeechResults recognize(final File audio, final String contentType)
public SpeechResults recognize(Map<String, Object> params)

What if these 2 methods were added?

public SpeechResults recognize(final File audio, final String contentType,Map<String, Object> params)
public SpeechResults recognize(AudioInputStream ais,Map<String, Object> params)

param would just be used for supplemental information, and the typed and named method parameters are used to get the data.

Ideally, I think removing the existing methods (or leaving them just for compatibility and having them delegate to the new methods) and using a builder pattern with a couple of convenience methods would be better. Like this:

public SpeechResults recognize(File file, String contentType, RecognizeOptions options);
public SpeechResults recognize(AudioInputStream ais, RecognizeOptions options);

@lombok.Builder @lombok.Value
class RecognizeOptions {
// defaults should also be specified so none of these are ever null
@NonNull
String model;
float wordConfidence;
boolean continuous;
int maxAlternatives;
boolean timestamps;
int inactivityTimeout;
}

The advantage of this approach is that the API becomes discoverable (just look at the RecognizeOptions class you can see all the options), strongly typed (so it's more typo-proof), subsequent releases of this library could add to RecognizeOptions and maintain ABI and API compatibility with previous versions (which I suspect is a major reason why you used a Map in the first place), and data and is separated from options (so options can be reused instead of continuously re-created).

I'm using Lombok's builder and value annotations, but the same could be achieved without Lombok - it just makes things easier.

[germanattanasio]

This is really good feedback @candrews... Let me talk to the team since this isn't a small change.

[nfriedly]

Just to chime in my opinion, I think Craig made some good points - it is some work but I think it's probably worth doing.

[germanattanasio]

I'm closing this since we decided to use @candrews's approach instead of a Map<String,Object> example