c@174: 
c@174: @0xc4b1c6c44c999206;
c@174: 
c@174: using Cxx = import "/capnp/c++.capnp";
c@174: $Cxx.namespace("piper");
c@174: 
c@174: struct Basic {
cannam@195:     # Basic metadata common to many Piper structures.
cannam@195: 
cannam@196:     identifier         @0  :Text;                 # A computer-readable string. Must match the regex /^[a-zA-Z0-9_-]+$/.
cannam@196:     name               @1  :Text;                 # A short human-readable name or label. Must be present.
cannam@196:     description        @2  :Text;                 # An optional human-readable descriptive text that may accompany the name.
c@174: }
c@174: 
c@174: struct ParameterDescriptor {
cannam@196:     # Properties of an adjustable parameter. A parameter's value is just a single
cannam@195:     # float, but the descriptor explains how to interpret and present that value.
cannam@196:     # A Piper feature extractor has a static list of parameters. The properties of
cannam@196:     # a given parameter never change, in contrast to output descriptors, which
cannam@196:     # may have different properties depending on the configuration of the extractor.
cannam@195: 
cannam@196:     basic              @0  :Basic;                # Basic metadata about the parameter.
cannam@196:     unit               @1  :Text;                 # Human-recognisable unit of the parameter (e.g. Hz). May be left empty.
cannam@196:     minValue           @2  :Float32     = 0.0;    # Minimum value. Must be provided.
cannam@196:     maxValue           @3  :Float32     = 0.0;    # Maximum value. Must be provided.
cannam@196:     defaultValue       @4  :Float32     = 0.0;    # Default if the parameter is not set to anything else. Must be provided.
cannam@196:     isQuantized        @5  :Bool        = false;  # True if parameter values are quantized to a particular resolution.
cannam@196:     quantizeStep       @6  :Float32     = 0.0;    # Quantization resolution, if isQuantized.
cannam@196:     valueNames         @7  :List(Text)  = [];     # Optional human-readable labels for the values, if isQuantized.
c@174: }
c@174: 
c@174: enum SampleType {
cannam@195:     # How returned features are spaced on the input timeline.
cannam@195: 
cannam@196:     oneSamplePerStep   @0;                        # Each process input returns a feature aligned with that input's timestamp.
cannam@196:     fixedSampleRate    @1;                        # Features are equally spaced at a given sample rate.
cannam@196:     variableSampleRate @2;                        # Features have their own individual timestamps.
c@174: }
c@174: 
c@174: struct ConfiguredOutputDescriptor {
cannam@196:     # Properties of an output, that is, a single stream of features produced
cannam@196:     # in response to process and finish requests. A feature extractor may
cannam@196:     # have any number of outputs, and it always calculates and returns features
cannam@196:     # from all of them when processing; this is useful in cases where more
cannam@196:     # than one feature can be easily calculated using a single method.
cannam@196:     # This structure contains the properties of an output that are not static,
cannam@196:     # i.e. that may depend on the parameter values provided at configuration.
cannam@196: 
cannam@196:     unit               @0  :Text;                 # Human-recognisable unit of the bin values in output features. May be empty.
cannam@196:     hasFixedBinCount   @1  :Bool        = false;  # True if this output has an equal number of values in each returned feature.
cannam@196:     binCount           @2  :Int32       = 0;      # Number of values per feature for this output, if hasFixedBinCount.
cannam@196:     binNames           @3  :List(Text)  = [];     # Optional human-readable labels for the value bins, if hasFixedBinCount.
cannam@196:     hasKnownExtents    @4  :Bool        = false;  # True if all feature values fall within the same fixed min/max range.
cannam@196:     minValue           @5  :Float32     = 0.0;    # Minimum value in range for any value from this output, if hasKnownExtents.
cannam@196:     maxValue           @6  :Float32     = 0.0;    # Maximum value in range for any value from this output, if hasKnownExtents.
cannam@196:     isQuantized        @7  :Bool        = false;  # True if feature values are quantized to a particular resolution.
cannam@196:     quantizeStep       @8  :Float32     = 0.0;    # Quantization resolution, if isQuantized.
cannam@196:     sampleType         @9  :SampleType;           # How returned features from this output are spaced on the input timeline.
cannam@196:     sampleRate         @10 :Float32     = 0.0;    # Sample rate (features per second) if sampleType == fixedSampleRate.
cannam@196:     hasDuration        @11 :Bool        = false;  # True if features returned from this output will have a duration.
c@174: }
c@174: 
c@174: struct OutputDescriptor {
cannam@196:     # All the properties of an output, both static (the basic metadata) and
cannam@196:     # potentially dependent on configuration parameters (the configured descriptor).
cannam@196: 
cannam@196:     basic              @0  :Basic;                # Basic metadata about the output.
cannam@196:     configured         @1  :ConfiguredOutputDescriptor;    # Properties of the output that may depend on configuration parameters.
c@174: }
c@174: 
c@174: enum InputDomain {
cannam@196:     # Whether a feature extractor requires time-domain audio input (i.e.
cannam@196:     # "normal" or "unprocessed" audio samples) or frequency-domain input
cannam@196:     # (i.e. resulting from windowed, usually overlapping, short-time
cannam@196:     # Fourier transforms).
cannam@196: 
cannam@196:     timeDomain         @0;                        # The plugin requires time-domain audio samples as input.
cannam@196:     frequencyDomain    @1;                        # The plugin requires input to have been pre-processed using windowed STFTs.
c@174: }
c@174: 
c@174: struct ExtractorStaticData {
cannam@196:     # Static properties of a feature extractor. That is, metadata about the
cannam@196:     # extractor that are the same regardless of how you configure or run it.
cannam@196: 
cannam@196:     key                @0  :Text;                 # Composed string that identifies the extractor among all extractors (see docs).
cannam@196:     basic              @1  :Basic;                # Basic metadata about the extractor.
cannam@196:     maker              @2  :Text;                 # Human-readable text naming the author or vendor of the extractor.
cannam@196:     copyright          @3  :Text;                 # ??? review
cannam@196:     version            @4  :Int32;                # Version number of extractor; must increase if new algorithm changes outputs.
cannam@196:     category           @5  :List(Text);           # ??? review
cannam@196:     minChannelCount    @6  :Int32;                # Minimum number of input channels of audio this extractor can accept.
cannam@196:     maxChannelCount    @7  :Int32;                # Maximum number of input channels of audio this extractor can accept.
cannam@196:     parameters         @8  :List(ParameterDescriptor);    # List of configurable parameter properties for the feature extractor.
cannam@196:     programs           @9  :List(Text);           # ??? review
cannam@196:     inputDomain        @10 :InputDomain;          # Whether the extractor requires time-domain or frequency-domain input audio.
cannam@196:     basicOutputInfo    @11 :List(Basic);          # Basic metadata about all of the outputs of the extractor.
c@174: }
c@174: 
c@174: struct RealTime {
cannam@196:     # Time structure. When used as a timestamp, this is relative to "start
cannam@196:     # of audio".
cannam@196:     
cannam@196:     sec                @0  :Int32       = 0;      # Number of seconds.
cannam@196:     nsec               @1  :Int32       = 0;      # Number of nanoseconds. Must have same sign as sec unless sec == 0.
c@174: }
c@174: 
c@174: struct ProcessInput {
cannam@196:     # Audio and timing input data provided to a process request.
cannam@196: 
cannam@196:     inputBuffers       @0  :List(List(Float32));  # For each input channel, a single block of audio data (time or frequency domain).
cannam@196:     timestamp          @1  :RealTime;             # Time of start of input block (time-domain) or "centre" of it (frequency-domain).
c@174: }
c@174: 
c@174: struct Feature {
cannam@196:     # A single feature calculated and returned from a process or finish request.
cannam@196: 
cannam@196:     hasTimestamp       @0  :Bool        = false;  # True if feature has a timestamp. Must be true if on a variableSampleRate output.
cannam@196:     timestamp          @1  :RealTime;             # Timestamp of feature, if hasTimestamp.
cannam@196:     hasDuration        @2  :Bool        = false;  # True if feature has a duration. Must be true if output's hasDuration is true.
cannam@196:     duration           @3  :RealTime;             # Duration of feature, if hasDuration.
cannam@196:     label              @4  :Text;                 # Optional human-readable text attached to feature.
cannam@196:     featureValues      @5  :List(Float32) = [];   # The feature values themselves (of size binCount, if output hasFixedBinCount).
c@174: }
c@174: 
c@174: struct FeatureSet {
c@174:     struct FSPair {
c@174:         output         @0  :Text;
c@174:         features       @1  :List(Feature) = [];
c@174:     }
c@174:     featurePairs       @0  :List(FSPair);
c@174: }
c@174: 
cannam@191: struct Framing {
cannam@191:     stepSize           @0  :Int32;
cannam@191:     blockSize          @1  :Int32;
cannam@191: }
cannam@191: 
c@174: struct Configuration {
c@174:     struct PVPair {
c@174:         parameter      @0  :Text;
c@174:         value          @1  :Float32;
c@174:     }
c@174:     parameterValues    @0  :List(PVPair);
c@174:     currentProgram     @1  :Text;
c@174:     channelCount       @2  :Int32;
cannam@191:     framing            @3  :Framing;
c@174: }
c@174: 
c@174: enum AdapterFlag {
c@174:     adaptInputDomain   @0;
c@174:     adaptChannelCount  @1;
c@174:     adaptBufferSize    @2;
c@174: }
c@174: 
c@174: const adaptAllSafe :List(AdapterFlag) =
c@174:       [ adaptInputDomain, adaptChannelCount ];
c@174: 
c@174: const adaptAll :List(AdapterFlag) =
c@174:       [ adaptInputDomain, adaptChannelCount, adaptBufferSize ];
c@174: 
c@174: struct ListRequest {
c@179:     from               @0  :List(Text);
c@174: }
c@174: 
c@174: struct ListResponse {
c@174:     available          @0  :List(ExtractorStaticData);    
c@174: }
c@174: 
c@174: struct LoadRequest {
c@174:     key                @0  :Text;
c@174:     inputSampleRate    @1  :Float32;
c@174:     adapterFlags       @2  :List(AdapterFlag);
c@174: }
c@174: 
c@174: struct LoadResponse {
c@174:     handle             @0  :Int32;
c@174:     staticData         @1  :ExtractorStaticData;
c@174:     defaultConfiguration @2  :Configuration;
c@174: }
c@174: 
c@174: struct ConfigurationRequest {
c@174:     handle             @0  :Int32;
c@174:     configuration      @1  :Configuration;
c@174: }
c@174: 
c@174: struct ConfigurationResponse {
c@174:     handle             @0  :Int32;
c@174:     outputs            @1  :List(OutputDescriptor);
cannam@191:     framing            @2  :Framing;
c@174: }
c@174: 
c@174: struct ProcessRequest {
c@174:     handle             @0  :Int32;
c@174:     processInput       @1  :ProcessInput;
c@174: }
c@174: 
c@174: struct ProcessResponse {
c@174:     handle             @0  :Int32;
c@174:     features           @1  :FeatureSet;
c@174: }
c@174: 
c@174: struct FinishRequest {
c@174:     handle             @0  :Int32;
c@174: }
c@174: 
c@174: struct FinishResponse {
c@174:     handle             @0  :Int32;
c@174:     features           @1  :FeatureSet;
c@174: }
c@174: 
c@174: struct Error {
c@174:     code               @0  :Int32;
c@174:     message            @1  :Text;
c@174: }
c@174: 
c@174: struct RpcRequest {
c@174:     # Request bundle for use when using Cap'n Proto serialisation without
c@174:     # Cap'n Proto RPC layer. For Cap'n Proto RPC, see piper.rpc.capnp.
c@175:     id :union {
c@175:         number         @0  :Int32;
c@175:         tag            @1  :Text;
c@175:         none           @2  :Void;
c@175:     }
c@174:     request :union {
c@175: 	list           @3  :ListRequest;
c@175: 	load           @4  :LoadRequest;
c@175: 	configure      @5  :ConfigurationRequest;
c@175: 	process        @6  :ProcessRequest;
c@177: 	finish         @7  :FinishRequest;
c@177:         # finish gets any remaining calculated features and unloads
c@177:         # the feature extractor. Note that you can call finish at any
c@177:         # time -- even if you haven't configured or used the extractor,
c@177:         # it will unload any resources used and abandon the handle.
c@174:     }
c@174: }
c@174: 
c@174: struct RpcResponse {
c@174:     # Response bundle for use when using Cap'n Proto serialisation without
c@174:     # Cap'n Proto RPC layer. For Cap'n Proto RPC, see piper.rpc.capnp.
c@175:     id :union {
c@175:         number         @0  :Int32;
c@175:         tag            @1  :Text;
c@175:         none           @2  :Void;
c@175:     }
c@174:     response :union {
c@175:         error          @3  :Error;
c@175: 	list           @4  :ListResponse;
c@175: 	load           @5  :LoadResponse;
c@175: 	configure      @6  :ConfigurationResponse;
c@175: 	process        @7  :ProcessResponse;
c@175: 	finish         @8  :FinishResponse;
c@174:     }
c@174: }
c@174: