api.hh

Go to the documentation of this file.

 // This Source Code Form is licensed MPL-2.0: http://mozilla.org/MPL/2.0
#ifndef __ASE_API_HH__
#define __ASE_API_HH__
 
#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 bool        set_data          (const String &key, const Value &v) = 0;
  virtual Value       get_data          (const String &key) const = 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 {
protected:
  explicit     Device ();
public:
  // internal
  Track*                  _track             () const;          
  virtual void            _activate          () = 0;            
  virtual void            _deactivate        () = 0;            
  virtual void            _disconnect_remove () = 0;            
  // exported
  virtual bool       is_active     () = 0;      
  virtual DeviceInfo device_info   () = 0;      
  virtual DeviceS    get_devices   () const = 0; 
  virtual void       set_devices   (const DeviceS &devices) = 0; 
  void               remove_self   ();          
  // GUI handling
  virtual void       gui_toggle    () = 0;      
  virtual bool       gui_supported () = 0;      
  virtual bool       gui_visible   () = 0;      
};
 
struct ClipNote {
  int32  id = 0;            
  int8   channel = 0;       
  int8   key = 0;           
  bool   selected = 0;      
  int64  tick = 0;          
  int64  duration = 0;      
  float  velocity = 0;      
  float  fine_tune = 0;     
  bool   operator== (const ClipNote&) const;
};
 
class Clip : public virtual Gadget {
protected:
  explicit          Clip           ();
public:
  virtual bool      is_muted       () const = 0;                  
  virtual void      set_muted      (bool muted) = 0;              
  virtual double    volume         () const = 0;                  
  virtual void      volume         (double db) = 0;              
  virtual double    pan            () const = 0;                  
  virtual void      pan            (double pan) = 0;             
  virtual ClipNoteS all_notes      () const = 0;
  virtual void      all_notes      (const ClipNoteS &notes) = 0;
  virtual int64     end_tick       () const = 0;
  virtual void      end_tick       (int64 etick) = 0;
  virtual int64     start_tick     () const = 0; 
  virtual int64     stop_tick      () const = 0; 
  virtual void      assign_range   (int64 starttick, int64 stoptick) = 0; 
  virtual int32     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 int32           midi_channel        () const = 0;          
  virtual void            midi_channel        (int32 midichannel) = 0;
  virtual bool            is_master           () const = 0;          
  virtual bool            is_muted            () const = 0;          
  virtual void            set_muted           (bool muted) = 0;      
  virtual bool            is_solo             () const = 0;          
  virtual void            set_solo            (bool solo) = 0;       
  virtual double          volume              () const = 0;          
  virtual void            volume              (double db) = 0;       
  virtual double          pan                 () const = 0;          
  virtual void            pan                 (double pan) = 0;      
  virtual ClipS           launcher_clips      () = 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 {
protected:
  explicit                Project        ();
public:
  virtual void            bpm            (double bpm) = 0;
  virtual double          bpm            () const = 0;
  virtual void            numerator      (double num) = 0;
  virtual double          numerator      () const = 0;
  virtual void            denominator    (double den) = 0;
  virtual double          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 bool            remove_track   (Track&) = 0; 
  virtual TrackS          all_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 double          master_volume  () const = 0; 
  virtual void            master_volume  (double db) = 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;     
};
 
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; 
  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
 
#endif // __ASE_API_HH__