crabidy/crabidy-core/crabidy/v1/crabidy.proto

syntax = "proto3";
package crabidy.v1;

service CrabidyService {
  // System
  rpc Init(InitRequest) returns (InitResponse);

  // Library
  rpc GetLibraryNode(GetLibraryNodeRequest) returns (GetLibraryNodeResponse);
  // Creates a child node under a creatable parent (LibraryNode.is_creatable).
  // What creation means is provider-defined; under /tidal/search the title is
  // a search term and the created node holds its results. Idempotent: an
  // existing title returns the existing node.
  rpc CreateLibraryNode(CreateLibraryNodeRequest) returns (CreateLibraryNodeResponse);
  // Renames a node whose listing entry sets is_editable. For a search term
  // the title is the query, so a rename re-runs the search; the node's path
  // changes with the title. Renaming onto an existing sibling title merges
  // with it. Returns the renamed node at its new path.
  rpc RenameLibraryNode(RenameLibraryNodeRequest) returns (RenameLibraryNodeResponse);
  // Deletes a node whose listing entry sets is_deletable. Idempotent:
  // deleting an already-gone node succeeds. Returns the refreshed parent.
  rpc DeleteLibraryNode(DeleteLibraryNodeRequest) returns (DeleteLibraryNodeResponse);

  // Queue
  rpc Queue(QueueRequest) returns (QueueResponse);
  rpc Replace(ReplaceRequest) returns (ReplaceResponse);
  rpc Append(AppendRequest) returns (AppendResponse);
  rpc Remove(RemoveRequest) returns (RemoveResponse);
  rpc Insert(InsertRequest) returns (InsertResponse);
  rpc ClearQueue(ClearQueueRequest) returns (ClearQueueResponse);
  rpc SetCurrent(SetCurrentRequest) returns (SetCurrentResponse);
  rpc ToggleShuffle(ToggleShuffleRequest) returns (ToggleShuffleResponse);
  rpc ToggleRepeat(ToggleRepeatRequest) returns (ToggleRepeatResponse);
  rpc GetUpdateStream(GetUpdateStreamRequest) returns (stream GetUpdateStreamResponse);
  rpc SaveQueue(SaveQueueRequest) returns (SaveQueueResponse);

  // Playback
  rpc TogglePlay(TogglePlayRequest) returns (TogglePlayResponse);
  rpc Stop(StopRequest) returns (StopResponse);
  rpc ChangeVolume(ChangeVolumeRequest) returns (ChangeVolumeResponse);
  rpc ToggleMute(ToggleMuteRequest) returns (ToggleMuteResponse);
  rpc Next(NextRequest) returns (NextResponse);
  rpc Prev(PrevRequest) returns (PrevResponse);
  rpc RestartTrack(RestartTrackRequest) returns (RestartTrackResponse);
}

// System
message InitRequest {}
message InitResponse {
  Queue queue = 1;
  QueueModifiers mods = 2;
  QueueTrack queue_track = 3;
  PlayState play_state = 4;
  float volume = 5;
  bool mute = 6;
  TrackPosition position = 7;
}

// Library
message GetLibraryNodeRequest {
  string path = 1;
}
message GetLibraryNodeResponse {
  LibraryNode node = 1;
}

message CreateLibraryNodeRequest {
  // Path of the creatable parent, e.g. /tidal/search.
  string parent_path = 1;
  // Human-entered name; becomes the node title. The path segment is a
  // percent-encoded form of it, chosen by the provider.
  string title = 2;
}
message CreateLibraryNodeResponse {
  LibraryNode node = 1;
}

message RenameLibraryNodeRequest {
  // Path of the node to rename.
  string path = 1;
  // New human-entered title; the provider derives the new path segment.
  string new_title = 2;
}
message RenameLibraryNodeResponse {
  // The renamed node, at its (possibly changed) path.
  LibraryNode node = 1;
}

message DeleteLibraryNodeRequest {
  // Path of the node to delete.
  string path = 1;
}
message DeleteLibraryNodeResponse {
  // The parent node with the deleted child gone — what a client should
  // display after the delete, without a follow-up GetLibraryNode.
  LibraryNode parent = 1;
}

// Queue
message QueueRequest {
  repeated string paths = 1;
}
message QueueResponse {}

message ReplaceRequest {
  repeated string paths = 1;
}
message ReplaceResponse {}

message AppendRequest {
  repeated string paths = 1;
}
message AppendResponse {}

message RemoveRequest {
  repeated uint32 positions = 1;
}
message RemoveResponse {}

message InsertRequest {
  uint32 position = 1;
  repeated string paths = 2;
}
message InsertResponse {}

message SetCurrentRequest {
  uint32 position = 1;
}
message SetCurrentResponse {}

message ToggleShuffleRequest {}
message ToggleShuffleResponse {}

message ToggleRepeatRequest {}
message ToggleRepeatResponse {}

message SaveQueueRequest {
  string name = 1;
}
message SaveQueueResponse {}

message ClearQueueRequest {
  bool exclude_current = 1;
}
message ClearQueueResponse {}

// Stream
message GetUpdateStreamRequest {}
message GetUpdateStreamResponse {
  oneof update {
    Queue queue = 1;
    QueueModifiers mods = 2;
    QueueTrack queue_track = 3;
    PlayState play_state = 4;
    float volume = 5;
    bool mute = 6;
    TrackPosition position = 7;
  }
}

// Playback
message TogglePlayRequest {}
message TogglePlayResponse {}

message StopRequest {}
message StopResponse {}

message ChangeVolumeRequest {
  float delta = 1;
}
message ChangeVolumeResponse {}

message ToggleMuteRequest {}
message ToggleMuteResponse {}

message NextRequest {}
message NextResponse {}

message PrevRequest {}
message PrevResponse {}

message RestartTrackRequest {}
message RestartTrackResponse {}

// Data types
message LibraryNodeChild {
  string path = 1;
  string title = 2;
  bool is_queable = 3;
  // Children may be created under this node (see CreateLibraryNode).
  bool is_creatable = 4;
  // This node may be renamed (see RenameLibraryNode).
  bool is_editable = 5;
  // This node may be deleted (see DeleteLibraryNode).
  bool is_deletable = 6;
}

message QueueModifiers {
  bool shuffle = 1;
  bool repeat = 2;
}

message Queue {
  uint64 timestamp = 1;
  uint32 current_position = 2;
  // Without album
  repeated Track tracks = 3;
  // True while the server is still resolving queued paths into tracks: more
  // tracks will arrive in subsequent Queue updates. Clients may show a
  // loading indicator until an update carries resolving = false.
  bool resolving = 4;
}

message QueueTrack {
  uint32 queue_position = 1;
  // With album
  optional Track track = 2;
}

enum PlayState {
  PLAY_STATE_UNSPECIFIED = 0;
  PLAY_STATE_STOPPED = 1;
  PLAY_STATE_LOADING = 2;
  PLAY_STATE_PLAYING = 3;
  PLAY_STATE_PAUSED = 4;
}

message TrackPosition {
  uint32 duration = 1;
  uint32 position = 2;
}

message Album {
  string title = 1;
  optional string release_date = 2;
}

message Track {
  // Full library path including provider
  string path = 1;
  string artist = 2;
  string title = 3;
  optional uint32 duration = 4;
  optional Album album = 5;
}

message LibraryNode {
  // Full library path including provider
  string path = 1;
  string title = 2;
  repeated LibraryNodeChild children = 3;
  optional string parent = 4;
  repeated Track tracks = 5;
  bool is_queable = 6;
  // Children may be created under this node (see CreateLibraryNode).
  bool is_creatable = 7;
}