api.hh

Go to the documentation of this file.

 // This Source Code Form is licensed MPL-2.0: http://mozilla.org/MPL/2.0
#pragma once
 
#include <ase/member.hh>
#include <ase/value.hh>
 
namespace Ase {
 
// == Property hint constants ==
constexpr const char GUIONLY[] = ":G:r:w:";     
constexpr const char STORAGE[] = ":S:r:w:";     
constexpr const char STANDARD[] = ":S:G:r:w:";  
 
class SharedBase : public virtual VirtualBase,
                   public virtual std::enable_shared_from_this<SharedBase>
{};
 
enum class Error : int32_t {
  NONE                          = 0,
  PERMS                         = EPERM,
  IO                            = EIO,
  // resource exhaustion
  NO_MEMORY                     = ENOMEM,
  NO_SPACE                      = ENOSPC,
  NO_FILES                      = ENFILE,
  MANY_FILES                    = EMFILE,
  RETRY                         = EINTR,
  // file errors
  NOT_DIRECTORY                 = ENOTDIR,
  FILE_NOT_FOUND                = ENOENT,
  FILE_IS_DIR                   = EISDIR,
  FILE_EXISTS                   = EEXIST,
  FILE_BUSY                     = EBUSY,
  // Ase specific errors
  INTERNAL                      = 0x30000000,
  UNIMPLEMENTED,
  // File related errors
  FILE_EOF                      = 0x30001000,
  FILE_OPEN_FAILED,
  FILE_SEEK_FAILED,
  FILE_READ_FAILED,
  FILE_WRITE_FAILED,
  // content errors
  PARSE_ERROR                   = 0x30002000,
  NO_HEADER,
  NO_SEEK_INFO,
  NO_DATA_AVAILABLE,
  DATA_CORRUPT,
  WRONG_N_CHANNELS,
  FORMAT_INVALID,
  FORMAT_UNKNOWN,
  DATA_UNMATCHED,
  CODEC_FAILURE,
  BROKEN_ARCHIVE,
  BAD_PROJECT,
  NO_PROJECT_DIR,
  // Device errors
  DEVICE_NOT_AVAILABLE          = 0x30003000,
  DEVICE_ASYNC,
  DEVICE_BUSY,
  DEVICE_FORMAT,
  DEVICE_BUFFER,
  DEVICE_LATENCY,
  DEVICE_CHANNELS,
  DEVICE_FREQUENCY,
  DEVICES_MISMATCH,
  // miscellaneous errors
  WAVE_NOT_FOUND                = 0x30004000,
  INVALID_PROPERTY,
  INVALID_MIDI_CONTROL,
  OPERATION_BUSY,
};
ASE_DEFINE_ENUM_EQUALITY (Error);
constexpr bool operator! (Error error)  { return !std::underlying_type_t<Error> (error); }
const char* ase_error_blurb      (Error error);
Error       ase_error_from_errno (int sys_errno, Error fallback = Error::IO);
 
enum class MusicalTuning : uint8 {
  // Equal Temperament: http://en.wikipedia.org/wiki/Equal_temperament
  OD_12_TET, OD_7_TET, OD_5_TET,
  // Rational Intonation: http://en.wikipedia.org/wiki/Just_intonation
  DIATONIC_SCALE, INDIAN_SCALE, PYTHAGOREAN_TUNING, PENTATONIC_5_LIMIT, PENTATONIC_BLUES, PENTATONIC_GOGO,
  // Meantone Temperament: http://en.wikipedia.org/wiki/Meantone_temperament
  QUARTER_COMMA_MEANTONE, SILBERMANN_SORGE,
  // Well Temperament: http://en.wikipedia.org/wiki/Well_temperament
  WERCKMEISTER_3, WERCKMEISTER_4, WERCKMEISTER_5, WERCKMEISTER_6, KIRNBERGER_3, YOUNG,
};
ASE_DEFINE_ENUM_EQUALITY (MusicalTuning);
 
struct Choice {
  String ident;   
  String icon;    
  String label;   
  String blurb;   
  String notice;  
  String warning; 
  Choice () = default;
  Choice (IconString icon, String label, String blurb = "");
  Choice (String ident, IconString icon, String label, String blurb = "", String notice = "", String warning = "");
  Choice (String ident, String label, String blurb = "", String notice = "", String warning = "");
};
 
ChoiceS& operator+= (ChoiceS &choices, Choice &&newchoice);
 
struct TelemetryField {
  String  name;         
  String  type;         
  int64_t offset = 0;   
  int32   length = 0;   
};
 
class Emittable : public virtual SharedBase {
public:
  struct Connection : EventConnectionP {
    bool             connected  () const;
    void             disconnect () const;
  };
  virtual void       emit_event  (const String &type, const String &detail, const ValueR fields = {}) = 0;
  ASE_USE_RESULT
  virtual Connection on_event    (const String &eventselector, const EventHandler &eventhandler) = 0;
  virtual void       emit_notify (const String &detail) = 0;
  void               js_trigger  (const String &eventselector, JsTrigger callback);
};
 
class Property : public virtual Emittable {
protected:
  explicit        Property       ();
  virtual        ~Property       () = 0;
public:
  virtual String  name           () const;
  virtual void    name           (const String &n);
  virtual StringS metadata       () const = 0;
  virtual void    metadata       (const StringS &md);
  virtual String  ident          () const = 0;         
  virtual String  label          () const = 0;         
  virtual String  nick           () const = 0;         
  virtual String  unit           () const = 0;         
  virtual double  get_min        () const = 0;         
  virtual double  get_max        () const = 0;         
  virtual double  get_step       () const = 0;         
  virtual void    reset          () = 0;               
  virtual Value   value          () const = 0;         
  virtual bool    value          (const Value &v) = 0; 
  virtual double  get_normalized () const = 0;         
  virtual bool    set_normalized (double v) = 0;       
  virtual String  get_text       () const = 0;         
  virtual bool    set_text       (String v) = 0;       
  virtual bool    is_numeric     () const = 0;         
  virtual ChoiceS choices        () const = 0;         
  String          hints          () const;             
  String          blurb          () const;             
  String          descr          () const;             
  String          group          () const;             
};
 
class Object : public virtual Emittable {
protected:
  virtual      ~Object () = 0;
public:
};
 
class Gadget : public virtual Object {
protected:
  explicit            Gadget            ();
public:
  // Hierarchical parenting.
  virtual GadgetImpl* _parent           () const = 0;             
  virtual void        _set_parent       (GadgetImpl *parent) = 0; 
  ProjectImpl*        _project          () const;                 
  // Naming
  virtual String      name              () const = 0;
  virtual void        name              (const std::string &n) = 0;
  virtual String      type_nick         () const = 0;
  // Properties
  virtual StringS     list_properties   ();                 
  virtual PropertyP   access_property   (String ident);     
  virtual PropertyS   access_properties () = 0;             
  Value               get_value         (String ident);     
  bool                set_value         (String ident, const Value &v); 
  virtual StringS     read_only_properties () const;
  virtual bool        set_data          (const String &key, const Value &v) = 0;
  virtual Value       get_data          (const String &key) const = 0;
  virtual void        remove_self       () = 0;
};
 
struct DeviceInfo {
  String uri;          
  String name;         
  String category;     
  String description;  
  String website_url;  
  String creator_name; 
  String creator_url;  
};
 
class Device : public virtual Gadget {
public:
  virtual DeviceInfo device_info   () = 0;      
};
 
class Plugin : public virtual Device {
public:
  virtual String  plugin_type   () const = 0; 
  virtual bool    enabled       () const = 0; 
  virtual void    enabled       (bool enabled) = 0; 
  virtual bool    frozen        () const = 0; 
  virtual void    frozen        (bool frozen) = 0; 
};
 
struct ClipNote {
  int32  id = 0;            
  int    note_number = 0;   
  double start_beat = 0;    
  double length_beats = 0;  
  int    velocity = 0;      
  int    colour = 0;        
  bool   mute = false;      
  bool   operator== (const ClipNote&) const = default;
};
 
struct TimeRange {
  double start = 0;
  double end = 0;
  bool operator== (const TimeRange&) const = default;
};
 
struct ClipPosition {
  TimeRange time;
  double offset = 0;
  bool operator== (const ClipPosition&) const = default;
};
 
class Clip : public virtual Gadget {
public:
  virtual bool      muted          () const = 0; 
  virtual void      muted          (bool muted) = 0; 
  virtual float     volume         () const = 0; 
  virtual void      volume         (float db) = 0; 
  virtual float     pan            () const = 0; 
  virtual void      pan            (float pan) = 0; 
  virtual ClipNoteS all_notes      () const = 0;
  virtual void      all_notes      (const ClipNoteS &notes) = 0;
  virtual ClipPosition position    () const = 0;
  virtual void      position       (const ClipPosition &position) = 0;
  virtual double    start_beat     () const = 0; 
  virtual void      start_beat     (double) = 0; 
  virtual double    end_beat       () const = 0; 
  virtual void      end_beat       (double) = 0; 
  virtual ClipNoteS change_batch   (const ClipNoteS &notes, const String &undogroup = "") = 0; 
  virtual ClipNoteS list_all_notes () = 0; 
  virtual TelemetryFieldS telemetry () const = 0; 
};
 
class Track : public virtual Device {
public:
  virtual bool            is_master           () const = 0;          
  virtual bool            is_control_track    () const = 0;          
  virtual bool            muted               () const = 0;          
  virtual void            muted               (bool muted) = 0;      
  virtual bool            hidden              () const = 0;          
  virtual void            hidden              (bool hidden) = 0;     
  virtual bool            solo                () const = 0;          
  virtual void            solo                (bool solo) = 0;       
  virtual float           volume_db           () const = 0;          
  virtual void            volume_db           (float db) = 0;        
  virtual float           slider_pos          () const = 0;          
  virtual void            slider_pos          (float pos) = 0;       
  virtual float           pan                 () const = 0;          
  virtual void            pan                 (float pan) = 0;       
  virtual ClipS           launcher_clips      () const = 0;          
  virtual void            launcher_clips      (const ClipS &) = 0;   
  virtual ClipP           create_midi_clip    (const String &name, double start, double length) = 0; 
  virtual ClipP           create_audio_clip   (const String &name, double start, double length) = 0; 
  virtual PluginP         create_plugin       (const String &type) = 0; 
  virtual PluginS         list_plugins        () = 0;                
  virtual DeviceP         access_device       () = 0;                
  virtual MonitorP        create_monitor      (int32 ochannel) = 0;  
  virtual TelemetryFieldS telemetry           () const = 0;          
};
 
struct ProbeFeatures {
  bool probe_range;     
  bool probe_energy;    
  bool probe_samples;   
  bool probe_fft;       
};
 
class Monitor : public virtual Gadget {
public:
  virtual DeviceP get_output         () = 0;            
  virtual int32   get_ochannel       () = 0;            
  virtual int64   get_mix_freq       () = 0;            
  virtual int64   get_frame_duration () = 0;            
  //int64         get_shm_offset     (MonitorField fld);  ///< Offset into shared memory for MonitorField values of `ochannel`.
  //void          set_probe_features (ProbeFeatures pf);  ///< Configure probe features.
  //ProbeFeatures get_probe_features ();                  ///< Get configured probe features.
};
 
class Project : public virtual Device {
public:
  virtual void            bpm            (double bpm) = 0;
  virtual double          bpm            () const = 0;
  virtual void            numerator      (int num) = 0;
  virtual int             numerator      () const = 0;
  virtual void            denominator    (int den) = 0;
  virtual int             denominator    () const = 0;
  virtual void            discard        () = 0;       
  virtual void            start_playback () = 0;       
  virtual void            pause_playback () = 0;       
  virtual void            stop_playback  () = 0;       
  virtual bool            is_playing     () const = 0; 
  virtual void            is_playing     (bool) = 0;   
  virtual TrackP          create_track   () = 0;       
  virtual TrackS          all_tracks     () const = 0; 
  virtual void            all_tracks     (const TrackS &) = 0; 
  virtual TrackP          master_track   () = 0;       
  virtual Error           save_project   (const String &utf8filename, bool collect) = 0; 
  virtual String          saved_filename () = 0;       
  virtual Error           load_project   (const String &utf8filename) = 0; 
  virtual TelemetryFieldS telemetry      () const = 0; 
  virtual void            group_undo     (const String &undoname) = 0; 
  virtual void            ungroup_undo   () = 0;                       
  virtual void            undo           () = 0;       
  virtual bool            can_undo       () = 0;       
  virtual void            redo           () = 0;       
  virtual bool            can_redo       () = 0;       
  virtual double          length         () const = 0; 
  virtual void            length         (double) = 0; 
  virtual String          match_serialized (const String &regex,
                                            int group = 0) = 0; 
  static ProjectP         last_project   ();
};
 
enum class ResourceType {
  FOLDER = 1,
  FILE,
};
 
struct Resource {
  ResourceType type = {};       
  String       label;           
  String       uri;             
  int64        size = 0;        
  int64        mtime = 0;       
};
 
class ResourceCrawler : public virtual Object {
protected:
  explicit          ResourceCrawler ();
public:
  virtual Resource  folder          () const = 0;                       
  virtual void      folder          (const Resource &newfolder) = 0;
  virtual ResourceS entries         () const = 0;                       
  virtual void      entries         (const ResourceS &newentries) = 0;
  using String2 = std::pair<String,String>;
  virtual String2   assign          (const String &utf8path,
                                     bool existingfile = false) = 0;    
  virtual Resource  canonify        (const String &utf8cwd, const String &utf8fragment, bool constraindir, bool constrainfile) = 0;
};
 
struct UserNote {
  enum Flags { APPEND, CLEAR, TRANSIENT };
  uint   noteid = 0;
  Flags  flags = APPEND;
  String channel, text, rest;
};
 
struct TelemetrySegment {
  int32 offset = 0;     
  int32 length = 0;     
};
 
struct UiConfig {
  bool has_ui_tests = false;    
  bool auto_exit = false;       
};
 
class Server : public virtual Gadget {
public:
  // singleton
  using ServerP = std::shared_ptr<Server>;
  static Server& instance           ();         
  static ServerP instancep          ();         
  virtual void   shutdown           () = 0;     
  virtual String get_version        () = 0;     
  virtual String get_build_id       () = 0;     
  virtual String get_opus_version   () = 0;     
  virtual String get_flac_version   () = 0;     
  virtual String get_sndfile_version() = 0;     
  virtual String error_blurb          (Error error) const = 0;
  virtual String musical_tuning_label (MusicalTuning musicaltuning) const = 0;
  virtual String musical_tuning_blurb (MusicalTuning musicaltuning) const = 0;
  virtual uint64 user_note            (const String &text, const String &channel = "misc", UserNote::Flags flags = UserNote::TRANSIENT, const String &rest = "") = 0;
  virtual bool   user_reply           (uint64 noteid, uint r) = 0;
  virtual bool   broadcast_telemetry  (const TelemetrySegmentS &segments,
                                       int32 interval_ms) = 0;   
  virtual StringS   list_preferences  () = 0;                    
  virtual PropertyP access_preference (const String &ident) = 0; 
  virtual UiConfig  ui_config         () = 0;                    
  virtual String    ui_test_fetch     () = 0;                    
  virtual void      ui_test_report    (const String &testname, bool success) = 0; 
  virtual String    ui_js_fetch       () = 0;                    
  String            engine_stats      ();                        
  void              exit_program      (int status = 0);          
  // projects
  virtual ProjectP last_project   () = 0;       
  virtual ProjectP create_project (String projectname) = 0; 
  // Browsing
  ResourceCrawlerP dir_crawler    (const String &cwd);
  ResourceCrawlerP url_crawler    (const String &url);
};
#define ASE_SERVER      (::Ase::Server::instance())
 
} // Ase