LogoFerret

Protocol reference#

Generated from proto/ by scripts/docs.sh reference. Do not edit by hand.

Every message travels inside an Envelope (see ferret.v1), whose feature field names the feature and whose type field is the full message name below.

ferret.actions.v1#

enum ActionKind#

What an action does on the computer that offers it.

ValueNumberMeaning
ACTION_KIND_UNSPECIFIED0
ACTION_KIND_SLEEP1Puts the computer to sleep.
ACTION_KIND_RESTART 2 Restarts the computer, after a countdown its owner can cancel.
ACTION_KIND_SHUT_DOWN 3 Turns the computer off, after a countdown its owner can cancel.
ACTION_KIND_MUTE 4 Mutes the sound, or brings it back when it is muted.
ACTION_KIND_VOLUME_UP5
ACTION_KIND_VOLUME_DOWN6
ACTION_KIND_CUSTOM 7 A command its owner defined on the computer. The command line never leaves that computer: only id and title do.

message Action#

Something a computer can do when a paired device asks.

FieldTypeNumberMeaning
id string 1 Stays the same for as long as the action exists: sleep , restart , shut_down , mute , volume_up , volume_down , or custom.<random> for the owner's own.
kindActionKind2
title string 3 The owner's name for a custom action. Empty for the others: the asking device words those itself, in its own language.
confirm bool 4 The asking device should confirm with its user before sending RunAction , because the computer is out of reach afterwards.

message ActionList#

Every action a computer offers the receiver right now. Sent without expecting a reply when a session opens and whenever the list changes. A device that never got one shows no actions.

FieldTypeNumberMeaning
actionsrepeated Action1

message RunAction#

Asks the computer to run one of its actions. Expects a RunActionReply, which can take a minute: the computer may ask its owner first, and counts down before it restarts or shuts down.

FieldTypeNumberMeaning
id string 1 An Action.id from the computer's ActionList. Never a command line.

enum RunResult#

How a RunAction went.

ValueNumberMeaning
RUN_RESULT_UNSPECIFIED0
RUN_RESULT_DONE 1 It ran. For sleep, restart and shut down: it is about to.
RUN_RESULT_DENIED2The owner said no on the computer.
RUN_RESULT_NOT_ANSWERED 3 Nobody answered the question on the computer in time.
RUN_RESULT_BUSY 4 The computer is asking about, or counting down, another request.
RUN_RESULT_TURNED_OFF 5 Actions are turned off on the computer.
RUN_RESULT_UNKNOWN_ACTION 6 No action has that id, such as one its owner removed.
RUN_RESULT_FAILED 7 It was tried and didn't work. For a custom action: it couldn't start, or ended with a non-zero exit_code .
RUN_RESULT_CANCELLED 8 Someone cancelled the countdown on the computer.
RUN_RESULT_TIMED_OUT 9 A custom action ran longer than the computer allows and was stopped.

message RunActionReply#

The reply to RunAction. What a custom action printed stays on the computer.

FieldTypeNumberMeaning
resultRunResult1
exit_code optional sint32 2 How a custom action's command ended. Only set when it ran to its end.

ferret.calls.v1#

enum CallDirection#

Who started a call.

ValueNumberMeaning
CALL_DIRECTION_UNSPECIFIED0
CALL_DIRECTION_INCOMING1Someone is calling the phone.
CALL_DIRECTION_OUTGOING2The phone is calling someone.

enum CallState#

Where a call is in its life.

ValueNumberMeaning
CALL_STATE_UNSPECIFIED0
CALL_STATE_RINGING1An incoming call nobody answered yet.
CALL_STATE_DIALING 2 An outgoing call. Phones that can't tell when the other side picks up stay in this state until the call ends.
CALL_STATE_ACTIVE3
CALL_STATE_HELD4
CALL_STATE_ENDED 5 The call is over. The last update for its id.

enum CallOutcome#

How a call that rang ended, when the phone knows.

ValueNumberMeaning
CALL_OUTCOME_UNSPECIFIED0
CALL_OUTCOME_ANSWERED1
CALL_OUTCOME_MISSED2It rang out, or the caller gave up.
CALL_OUTCOME_DECLINED3Someone declined it through Ferret.

message Call#

One call on a phone.

FieldTypeNumberMeaning
id string 1 Random id chosen by the phone, the same in every update for this call.
number string 2 The other side's number as the phone reports it. Empty when it is hidden or the phone may not read it.
contact_name string 3 The contact's name, empty when the number is not in the contacts.
photo_jpeg bytes 4 The contact's photo as a small JPEG, at most 96 pixels a side.
directionCallDirection5
stateCallState6
started_at_ms int64 7 When the call started ringing or dialing, in the phone's clock.
connected_at_ms int64 8 When the call was picked up, in the phone's clock. Zero until then.
outcome CallOutcome 9 Set with CALL_STATE_ENDED.

message CallUpdate#

A call changed. Sent by the phone without expecting a reply, for every change, and once for each ongoing call when a session opens. Calls that already ended are never replayed.

FieldTypeNumberMeaning
callCall1
sent_at_ms int64 2 The phone's clock when it sent this, so receivers can show a call timer that does not depend on both clocks agreeing.

enum CallAction#

What a computer asks the phone to do with a call.

ValueNumberMeaning
CALL_ACTION_UNSPECIFIED0
CALL_ACTION_ANSWER 1 Pick up the ringing call. Audio stays on the phone.
CALL_ACTION_END 2 Decline the ringing call, or hang up the ongoing one.
CALL_ACTION_SILENCE3Stop the ringtone without declining.
CALL_ACTION_DIAL4Call number.

message CallCommand#

Request. The phone replies with CallCommandResult.

FieldTypeNumberMeaning
actionCallAction1
call_id string 2 The call the command is for. The phone refuses a command for a call that is gone. Unused for CALL_ACTION_DIAL.
number string 3 The number to call, for CALL_ACTION_DIAL.

enum CallCommandStatus#

ValueNumberMeaning
CALL_COMMAND_STATUS_UNSPECIFIED0
CALL_COMMAND_STATUS_OK1
CALL_COMMAND_STATUS_NO_CALL 2 The call is gone, or nothing is ringing.
CALL_COMMAND_STATUS_DISABLED 3 Calls are turned off on the phone.
CALL_COMMAND_STATUS_PERMISSION_MISSING 4 The phone's owner did not give Ferret the permission this needs.
CALL_COMMAND_STATUS_UNSUPPORTED 5 This phone's system version can't do it.
CALL_COMMAND_STATUS_INVALID_NUMBER 6 The number is empty or has characters a phone can't dial.
CALL_COMMAND_STATUS_FAILED7

message CallCommandResult#

FieldTypeNumberMeaning
statusCallCommandStatus1

message GetCallsStatus#

Request. The phone replies with CallsStatus.

message CallsStatus#

What the phone can do right now. Also sent on its own when it changes.

FieldTypeNumberMeaning
enabled bool 1 The phone's owner turned calls on.
can_see_calls bool 2 The phone may watch its call state.
can_see_numbers bool 3 The phone may read who is calling.
can_answer bool 4 The phone may answer and end calls.
can_dial bool 5 The phone may place calls.
can_read_log bool 6 The phone may read its call history.
can_read_contacts bool 7 The phone may look numbers up in its contacts.

enum CallLogType#

What a past call was.

ValueNumberMeaning
CALL_LOG_TYPE_UNSPECIFIED0
CALL_LOG_TYPE_INCOMING1
CALL_LOG_TYPE_OUTGOING2
CALL_LOG_TYPE_MISSED3
CALL_LOG_TYPE_REJECTED4The phone's owner declined it.

message CallLogEntry#

One past call.

FieldTypeNumberMeaning
id string 1 The phone's own id for the entry.
numberstring2
name string 3 The contact's name, empty when unknown.
typeCallLogType4
date_ms int64 5 When the call happened, in the phone's clock.
duration_s int64 6 How long the call lasted, zero when it was not picked up.

message GetCallLog#

Request. The phone replies with CallLog.

FieldTypeNumberMeaning
limit uint32 1 The most entries to send back, newest first. Zero means 50; the phone never sends more than 200.

message CallLog#

FieldTypeNumberMeaning
entriesrepeated CallLogEntry1
permission_missing bool 2 The phone may not read its call history, so entries is empty.
disabled bool 3 Calls are turned off on the phone, so entries is empty.

ferret.camera.v1#

enum CaptureKind#

What the computer asks for.

ValueNumberMeaning
CAPTURE_KIND_UNSPECIFIED0
CAPTURE_KIND_PHOTO1
CAPTURE_KIND_DOCUMENT 2 A scanned document: a JPEG for one page, a PDF for several. iPhone only.

enum CaptureStatus#

Where a request stands.

ValueNumberMeaning
CAPTURE_STATUS_UNSPECIFIED0
CAPTURE_STATUS_ASKING 1 The phone shows the request and waits for its owner.
CAPTURE_STATUS_TAKEN 2 A picture was taken; transfer_id names the drop transfer carrying it.
CAPTURE_STATUS_DECLINED3The owner answered "Not now".
CAPTURE_STATUS_CANCELLED 4 The camera closed without a picture.
CAPTURE_STATUS_UNSUPPORTED 5 This phone can't take that kind of picture, such as a document scan on Android.
CAPTURE_STATUS_NO_PERMISSION 6 The phone's system didn't let Ferret use the camera.
CAPTURE_STATUS_BUSY 7 The camera is already open for another request.
CAPTURE_STATUS_FAILED8
CAPTURE_STATUS_EXPIRED9Nobody answered on the phone in time.

message CaptureRequest#

Asks the phone for a picture (a request, answered with CaptureReply right away; the picture comes later with CaptureResult).

FieldTypeNumberMeaning
request_id string 1 Chosen by the asking device; unique among its requests.
kindCaptureKind2

message CaptureReply#

FieldTypeNumberMeaning
request_idstring1
status CaptureStatus 2 ASKING when the phone shows the request, else why it can't.

message CaptureResult#

How a request ended, sent by the phone. No reply.

FieldTypeNumberMeaning
request_idstring1
statusCaptureStatus2
transfer_id string 3 The drop transfer carrying the picture, when status is TAKEN. The asking device accepts it on its own: it asked for it.
mime_type string 4 Such as "image/jpeg" or "application/pdf".

message CaptureCancel#

The asking device doesn't want the picture any more: the phone takes the request away. A picture taken after this is thrown away. No reply.

FieldTypeNumberMeaning
request_idstring1

ferret.clipboard.v1#

enum ClipKind#

What a clip holds, so receivers can preview it without parsing.

ValueNumberMeaning
CLIP_KIND_UNSPECIFIED0
CLIP_KIND_TEXT1
CLIP_KIND_IMAGE2
CLIP_KIND_URL3Text that is a single http or https link.

message ClipItem#

One thing someone copied.

FieldTypeNumberMeaning
id string 1 Random id chosen by the source device, used to drop duplicates.
kindClipKind2
text string 3 Set for CLIP_KIND_TEXT and CLIP_KIND_URL.
image bytes 4 Encoded image bytes, set for CLIP_KIND_IMAGE.
image_mime string 5 Media type of image, such as "image/png".
created_at_ms int64 6 When it was copied, in the source device's clock.
source_device_id string 7 Device id of the device it was copied on.
sensitive bool 8 The source app marked it as private, such as a password manager. Receivers keep it out of history and clipboard managers.
content_hash bytes 9 SHA-256 of the content (kind, text or image bytes), so devices can drop echoes of what they wrote themselves.

message ClipPush#

Puts item on the receiver's clipboard. Sent without expecting a reply.

FieldTypeNumberMeaning
itemClipItem1
expires_in_ms int64 2 How long the item stays useful after created_at_ms . Receivers drop sensitive items from memory once it passes.

ferret.drop.v1#

message FileInfo#

One file in a transfer offer.

FieldTypeNumberMeaning
name string 1 Base name only; the receiver never trusts it as a path.
sizeuint642
mimestring3
sha256 bytes 4 SHA-256 of the whole file when the sender knows it up front. The authoritative hash always arrives in FileComplete.
folder string 5 The folder the file sits in when a whole folder is sent, relative and separated by "/": "Photos" or "Photos/2024". The first part is the folder that was sent. Empty for a file sent on its own. Senders only fill it for receivers whose drop FeatureSupport has the "folders" flag; receivers clean every part and never write outside their receive folder.
modified_ms int64 6 When the file was last modified, in milliseconds since the Unix epoch, or 0 when unknown. Receivers keep it where the platform allows.

message TransferOffer#

Asks to send files or text (a request, answered with TransferAnswer). Sending the same transfer_id again after a dropped session resumes it.

FieldTypeNumberMeaning
transfer_idstring1
filesrepeated FileInfo2
text string 3 Text to drop instead of, or along with, files.
chunk_size uint32 4 Size of each chunk the sender will send.

message TransferAnswer#

The answer to a TransferOffer.

FieldTypeNumberMeaning
transfer_idstring1
acceptedbool2
reasonDeclineReason3
file_index uint32 4 Where to start sending: the first file that isn't complete yet and the byte offset in it. Both are 0 for a new transfer.
offsetuint645

enum DeclineReason#

ValueNumberMeaning
DECLINE_REASON_UNSPECIFIED0
DECLINE_REASON_DECLINED 1 Someone on the receiving device said no.
DECLINE_REASON_TIMEOUT2Nobody answered in time.
DECLINE_REASON_STORAGE 3 The receiver can't write to its receive folder.
DECLINE_REASON_UNKNOWN_TRANSFER 4 The receiver doesn't know this transfer any more and can't resume it.
DECLINE_REASON_INVALID 5 The offer is malformed, such as a file without a name.

message Chunk#

A piece of one file. Every few chunks are sent as a request, answered with ChunkReceived once the receiver wrote them, which bounds the data in flight.

FieldTypeNumberMeaning
transfer_idstring1
file_indexuint322
offsetuint643
databytes4

message ChunkReceived#

Confirms the receiver wrote everything up to offset of file_index.

FieldTypeNumberMeaning
transfer_idstring1
file_indexuint322
offsetuint643

message FileComplete#

The last chunk of a file was sent (a request, answered with FileVerified).

FieldTypeNumberMeaning
transfer_idstring1
file_indexuint322
sha256bytes3

message FileVerified#

Whether the receiver's copy matched the hash and was saved.

FieldTypeNumberMeaning
transfer_idstring1
file_indexuint322
okbool3
reasonFailureReason4

message TransferComplete#

Every file was sent and verified.

FieldTypeNumberMeaning
transfer_idstring1

message Cancel#

Either side stops a transfer.

FieldTypeNumberMeaning
transfer_idstring1
reasonFailureReason2

enum FailureReason#

ValueNumberMeaning
FAILURE_REASON_UNSPECIFIED0
FAILURE_REASON_CANCELLED1Someone cancelled it.
FAILURE_REASON_CHECKSUM 2 The received data didn't match the sender's SHA-256.
FAILURE_REASON_STORAGE 3 Reading or writing a file failed, such as a full disk.
FAILURE_REASON_SOURCE_CHANGED 4 The sender's file changed or disappeared during the transfer.
FAILURE_REASON_PROTOCOL 5 A chunk didn't match what the receiver expected.
FAILURE_REASON_UNKNOWN_TRANSFER 6 The sender no longer has this transfer, so it can't be resumed.

message ResumeRequest#

Sent by a receiver after a dropped session comes back, to continue an interrupted transfer where it stopped.

FieldTypeNumberMeaning
transfer_idstring1
file_indexuint322
offsetuint643

ferret.find.v1#

message RingRequest#

Asks the receiver to ring so someone can find it. Expects a RingStatus reply. Asking a device that already rings restarts its countdown.

FieldTypeNumberMeaning
duration_seconds uint32 1 How long to ring before stopping on its own. 0 means the receiver's default; receivers cap long values.
override_silent bool 2 Ring even when the receiver is on silent or Do Not Disturb, if its owner allowed that on the receiver.

message StopRingRequest#

Asks the receiver to stop ringing. Expects a RingStatus reply.

enum RingState#

Whether a device rings.

ValueNumberMeaning
RING_STATE_UNSPECIFIED0
RING_STATE_RINGING1
RING_STATE_STOPPED2

enum StopReason#

Why a ring stopped.

ValueNumberMeaning
STOP_REASON_UNSPECIFIED0
STOP_REASON_FOUND 1 Someone tapped "Found it" or pressed a volume key on the ringing device.
STOP_REASON_TIMEOUT2The ring ran for its whole duration.
STOP_REASON_STOPPED_REMOTELY 3 A StopRingRequest arrived.
STOP_REASON_FAILED4The device could not play a sound at all.

message RingStatus#

Where a ring stands. The reply to RingRequest and StopRingRequest, and sent without expecting a reply to each device that asked for the ring when it stops on the ringing device.

FieldTypeNumberMeaning
stateRingState1
reason StopReason 2 Set when state is RING_STATE_STOPPED.
remaining_ms uint32 3 Milliseconds left until the ring stops on its own, while ringing.
muted bool 4 It rings, but without sound, because it is on silent or Do Not Disturb and may not override that. It still vibrates and shows a notice.

message GetRingInfo#

Asks what the receiver can do when rung. Expects a RingInfo reply.

message RingInfo#

What the receiver can do when rung. The reply to GetRingInfo, and sent without expecting a reply when it changes, such as after a permission was granted.

FieldTypeNumberMeaning
ringingbool1It rings right now.
rings_when_silent bool 2 It rings out loud even on silent or Do Not Disturb.
needs_app_open bool 3 It can only ring while Ferret is open on it, such as on iOS.
needs_permission bool 4 Its owner turned ringing on silent on, but the system permission for it is missing.

ferret.handoff.v1#

enum ActivityKind#

What an activity is, which decides how the receiving device opens it.

ValueNumberMeaning
ACTIVITY_KIND_UNSPECIFIED0
ACTIVITY_KIND_WEB1A web page: uri is http(s).
ACTIVITY_KIND_APP 2 Something inside an app: deep_link and apps , with fallback_web_uri for devices that don't have the app.
ACTIVITY_KIND_GEO 3 A place: uri is a geo: URI (RFC 5870).
ACTIVITY_KIND_TEXT 4 Plain text in text, such as a note or an address.

message AppIdentifiers#

The app that can continue an activity, per platform. Empty when unknown.

FieldTypeNumberMeaning
android_package string 1 Android package name, such as "org.wikipedia".
apple_bundle_id string 2 Bundle id on macOS and iOS, such as "com.apple.Safari".
linux_desktop_id string 3 Desktop entry id on Linux, such as "org.gnome.Maps.desktop".
windows_app_id string 4 AppUserModelID on Windows.

message Activity#

Something the user is doing that another device can continue. Shaped like Android's HandoffActivityData: the activity itself, plus a web URI to fall back to when the app isn't there.

FieldTypeNumberMeaning
id string 1 Unique per activity, chosen by the source device.
kindActivityKind2
title string 3 Short, human title, such as the page title.
uri string 4 The main URI: http(s), geo: or mailto:.
deep_link string 5 A URI only the app understands, opened in the app named by apps.
appsAppIdentifiers6
fallback_web_uri string 7 Opened when no app can take deep_link.
text string 8 The text of an ACTIVITY_KIND_TEXT activity.
state bytes 9 Opaque state for apps that opted in, such as scroll position. Ferret never reads it; it is handed to the app as is.
state_type string 10 What state holds, such as "application/ld+json" for AssistContent structured data, or a reverse-DNS name chosen by the app.
created_at_msuint6411
expires_at_ms uint64 12 After this time the activity is stale and is not suggested any more.
source_device_id string 13 Device id of the device the activity comes from.
source_app_name string 14 Name of the app it comes from, such as "Firefox", for display only.

message PublishActivity#

Passive: "this is what I'm doing now". Receivers keep it as a quiet suggestion that expires and is replaced by the next one from the same device. Sent without expecting a reply.

FieldTypeNumberMeaning
activityActivity1

message ContinueActivity#

Explicit: "continue this on your side now". Sent as a request; the receiver answers with ContinueResult.

FieldTypeNumberMeaning
activityActivity1

enum ContinueOutcome#

What the receiver did with a ContinueActivity.

ValueNumberMeaning
CONTINUE_OUTCOME_UNSPECIFIED0
CONTINUE_OUTCOME_OPENED1Opened right away.
CONTINUE_OUTCOME_SUGGESTED 2 Kept as a suggestion with a notice, because the user turned automatic opening off.
CONTINUE_OUTCOME_FAILED 3 Could not open it, such as a URI scheme it doesn't accept.

message ContinueResult#

FieldTypeNumberMeaning
outcomeContinueOutcome1

message ClearActivity#

Withdraws suggestions from the sender, such as when the page was closed.

FieldTypeNumberMeaning
activity_id string 1 The activity to withdraw, or empty for every one from the sender.

ferret.media.v1#

message MediaState#

What a device is playing right now: every media player it can see. Sent when something changes (feature "media"), never on a timer: the receiver extrapolates the position of a playing item itself. An empty list means the device stopped sharing or nothing plays.

FieldTypeNumberMeaning
playersrepeated MediaPlayer1
sent_at_ms uint64 2 The sender's clock when it sent this, so the receiver can map the players' timestamps onto its own clock.

message MediaStateRequest#

Asks a device for its current MediaState (feature "media"). The reply is a MediaState.

message MediaPlayer#

One media player, such as Spotify or a browser tab, and what it plays.

FieldTypeNumberMeaning
player_id string 1 Stable while the player exists on the sender.
app_id string 2 The app behind the player, such as "com.spotify.music" on Android or "com.spotify.client" on macOS.
app_namestring3
titlestring4
artiststring5
albumstring6
artwork_id string 7 Identifies the artwork, so the image is sent only once per session.
artwork bytes 8 A small JPEG or PNG (at most 64 KiB). Empty when the receiver already got the image for artwork_id in this session.
duration_ms uint64 9 0 when unknown, such as a live stream.
position_ms uint64 10 The position at position_at_ms.
position_at_ms uint64 11 The sender's clock when position_ms was true.
statusMediaPlaybackStatus12
playback_rate float 13 Playback speed while playing; 0 means 1.
content_uri string 14 A link to the item, such as a YouTube URL or a spotify: URI, when the player tells it.
last_active_at_ms uint64 15 The sender's clock when this player last started playing or changed item, to follow the last active player.
actionsrepeated MediaAction16
volume float 17 Player volume 0 to 1, or -1 when unknown.

enum MediaPlaybackStatus#

ValueNumberMeaning
MEDIA_PLAYBACK_STATUS_UNSPECIFIED0
MEDIA_PLAYBACK_STATUS_STOPPED1
MEDIA_PLAYBACK_STATUS_PAUSED2
MEDIA_PLAYBACK_STATUS_PLAYING3
MEDIA_PLAYBACK_STATUS_BUFFERING4

enum MediaAction#

ValueNumberMeaning
MEDIA_ACTION_UNSPECIFIED0
MEDIA_ACTION_PLAY1
MEDIA_ACTION_PAUSE2
MEDIA_ACTION_TOGGLE3
MEDIA_ACTION_NEXT4
MEDIA_ACTION_PREVIOUS5
MEDIA_ACTION_SEEK6
MEDIA_ACTION_SET_VOLUME7

message MediaCommand#

Asks a device to control one of its players (feature "media"). The reply is a MediaCommandReply.

FieldTypeNumberMeaning
player_idstring1
actionMediaAction2
position_ms uint64 3 For MEDIA_ACTION_SEEK.
volume float 4 For MEDIA_ACTION_SET_VOLUME, 0 to 1.

message MediaCommandReply#

FieldTypeNumberMeaning
resultMediaCommandResult1

enum MediaCommandResult#

ValueNumberMeaning
MEDIA_COMMAND_RESULT_UNSPECIFIED0
MEDIA_COMMAND_RESULT_OK1
MEDIA_COMMAND_RESULT_UNKNOWN_PLAYER 2 No player with that id, such as one that just closed.
MEDIA_COMMAND_RESULT_NOT_SHARED 3 The user turned off sharing media on that device.
MEDIA_COMMAND_RESULT_UNSUPPORTED 4 The player can't do that action.
MEDIA_COMMAND_RESULT_FAILED5

message MediaContinueRequest#

Asks a device to hand one of its players over (feature "media"): it pauses the player when pause_source is set and replies with a MediaContinueReply holding the item and the position it stopped at.

FieldTypeNumberMeaning
player_idstring1
pause_sourcebool2

message MediaContinueReply#

FieldTypeNumberMeaning
resultMediaCommandResult1
player MediaPlayer 2 The player as it was when it paused, with a fresh position.
paused bool 3 Whether the source paused, so the receiver can resume it if opening the item here fails.

ferret.messages.v1#

enum MessageKind#

Where a message sits on the phone.

ValueNumberMeaning
MESSAGE_KIND_UNSPECIFIED0
MESSAGE_KIND_INBOX1Received.
MESSAGE_KIND_SENT2
MESSAGE_KIND_OUTBOX3Being sent right now.
MESSAGE_KIND_FAILED4
MESSAGE_KIND_QUEUED 5 Waiting to be sent, such as with no signal.

message Participant#

Someone in a conversation.

FieldTypeNumberMeaning
address string 1 The phone number or email address as the phone stores it.
name string 2 The contact's name on the phone, or empty when it isn't a contact.
avatar_jpeg bytes 3 A small JPEG of the contact's photo (at most 96 px), or empty.

message Conversation#

A conversation (an Android thread).

FieldTypeNumberMeaning
thread_idint641
participants repeated Participant 2 Everyone in it except the phone's owner.
snippet string 3 The last message's text, or empty when it was only an attachment.
last_date_msint644
unread_countuint325
is_group bool 6 More than one other person, as in a group MMS.

message Attachment#

A file in an MMS, such as a photo.

FieldTypeNumberMeaning
part_id string 1 The MMS part's id on the phone; send it back in FetchAttachment.
mimestring2
sizeint643Bytes, or 0 when unknown.
thumbnail_jpeg bytes 4 A small JPEG preview (at most 320 px) for images, or empty.
name string 5 The file name the sender gave, or empty.

message Message#

FieldTypeNumberMeaning
id string 1 Unique on the phone across SMS and MMS, such as "sms:12" or "mms:7".
thread_idint642
sender_address string 3 Who sent it, for received messages; empty for messages sent from the phone.
bodystring4
date_msint645
kindMessageKind6
attachmentsrepeated Attachment7
readbool8

message MessagesStatus#

What the source can do right now. Answers a StatusRequest, and is pushed without a request whenever it changes.

FieldTypeNumberMeaning
enabled bool 1 The person turned Messages on on the phone.
sms_access bool 2 The phone lets Ferret read SMS.
send_access bool 3 The phone lets Ferret send SMS.
contacts_access bool 4 The phone lets Ferret read contacts for names and photos.

message StatusRequest#

Expects a MessagesStatus reply.

message ListConversations#

Asks for conversations, most recent first. Expects a ConversationPage.

FieldTypeNumberMeaning
before_date_ms int64 1 Only conversations whose last message is older than this; 0 for the newest.
limituint322

message ConversationPage#

FieldTypeNumberMeaning
conversationsrepeated Conversation1
has_more bool 2 There are older conversations.

message ListMessages#

Asks for messages of one conversation, newest first. Expects a MessagePage.

FieldTypeNumberMeaning
thread_idint641
before_date_ms int64 2 Only messages at or before this date; 0 for the newest.
skip_ids repeated string 3 Messages at exactly before_date_ms the asker already has, so pages never skip messages that share a date.
limituint324

message MessagePage#

FieldTypeNumberMeaning
thread_idint641
messagesrepeated Message2
has_morebool3There are older messages.

message FetchAttachment#

Asks for one attachment in full. Expects an AttachmentData.

FieldTypeNumberMeaning
message_idstring1
part_idstring2

message AttachmentData#

FieldTypeNumberMeaning
mimestring1
databytes2

enum SendFailure#

Why a message wasn't sent.

ValueNumberMeaning
SEND_FAILURE_UNSPECIFIED0
SEND_FAILURE_NO_ACCESS1Ferret may not send SMS on the phone.
SEND_FAILURE_NO_RECIPIENT 2 No address to send to, or the conversation is gone.
SEND_FAILURE_GROUP 3 Group conversations need MMS, which only the default messaging app sends.
SEND_FAILURE_NO_SERVICE 4 The phone has no signal or the carrier refused it.
SEND_FAILURE_TIMEOUT5The radio didn't confirm in time.
SEND_FAILURE_OTHER6

message SendText#

Sends an SMS. Expects a SendResult.

FieldTypeNumberMeaning
thread_id int64 1 The conversation to answer, or 0 to start one with addresses.
addressesrepeated string2
textstring3

message SendResult#

FieldTypeNumberMeaning
okbool1
failureSendFailure2
thread_id int64 3 The conversation the message went to, when known.

message MarkRead#

Marks a conversation as read. Expects a MarkReadResult.

FieldTypeNumberMeaning
thread_idint641

message MarkReadResult#

FieldTypeNumberMeaning
applied bool 1 The phone changed it. Android lets only the default messaging app mark SMS as read, so this is usually false; computers then keep it read themselves.

message MessagesChanged#

New or changed messages and their conversations, pushed by the source without a reply. Only for changes seen while the session is open.

FieldTypeNumberMeaning
messagesrepeated Message1
conversationsrepeated Conversation2

ferret.mirroring.v1#

enum ControlStatus#

Where control stands on the source.

ValueNumberMeaning
CONTROL_STATUS_UNSPECIFIED0
CONTROL_STATUS_CAN_ASK 1 The source can be controlled. A ControlAsk makes it ask its owner.
CONTROL_STATUS_ASKING 2 The owner is being asked, for at most ControlState.timeout_seconds.
CONTROL_STATUS_ALLOWED 3 The viewer may send ControlInput.
CONTROL_STATUS_DENIED 4 The owner said no. The viewer may ask again later.
CONTROL_STATUS_TIMED_OUT5The owner didn't answer in time.
CONTROL_STATUS_NEEDS_SETUP 6 Nothing on the source can inject input until its owner sets it up there: the accessibility service is off and there are no power-ups.
CONTROL_STATUS_UNSUPPORTED 7 The source can't be controlled at all, such as an iPhone.
CONTROL_STATUS_STOPPED 8 The owner stopped control on the source. The viewer may ask again.

enum ControlKind#

What the source can take while control is allowed.

ValueNumberMeaning
CONTROL_KIND_UNSPECIFIED0
CONTROL_KIND_POINTER 1 Taps, drags and scrolling: PointerInput.
CONTROL_KIND_KEYS 2 Every ferret.remote_input.v1.Key, with modifiers.
CONTROL_KIND_TEXT3Typed text.
CONTROL_KIND_BUTTONS 4 The device's own buttons: ButtonPress.

message ControlState#

Sent by the source after StartAccept, and again whenever control changes. Expects no reply.

FieldTypeNumberMeaning
statusControlStatus1
kinds repeated ControlKind 2 What the source takes right now, or would take once allowed.
timeout_seconds uint32 3 With CONTROL_STATUS_ASKING: how long the owner has to answer.
buttons repeated ControlButton 4 The buttons a ButtonPress can press. Empty without CONTROL_KIND_BUTTONS.

message ControlAsk#

The viewer wants control. The source answers with ControlState: ASKING while its owner decides, then ALLOWED, DENIED or TIMED_OUT; ALLOWED at once for a viewer its owner always allows. Ignored while the source isn't showing its screen to this viewer.

message ControlRelease#

The viewer gives control back and only watches. The source answers with ControlState CAN_ASK.

enum TouchPhase#

What a pointer does.

ValueNumberMeaning
TOUCH_PHASE_UNSPECIFIED0
TOUCH_PHASE_DOWN 1 A finger goes down at (x, y).
TOUCH_PHASE_MOVE 2 The finger that is down moves to (x, y).
TOUCH_PHASE_UP 3 The finger lifts at (x, y).
TOUCH_PHASE_CANCEL 4 The touch is abandoned: nothing under it is activated.
TOUCH_PHASE_SCROLL 5 The content under ( x , y ) scrolls by scroll_x and scroll_y .

message PointerInput#

One step of a touch. Positions are fractions of the picture as the source sends it, in its current rotation: (0, 0) is the top left corner and (1, 1) the bottom right. The source clamps them to that range.

FieldTypeNumberMeaning
phaseTouchPhase1
xfloat2
yfloat3
scroll_x float 4 TOUCH_PHASE_SCROLL only, in wheel notches: positive is right.
scroll_y float 5 TOUCH_PHASE_SCROLL only, in wheel notches: positive is down.

enum ControlButton#

A button of the device itself.

ValueNumberMeaning
CONTROL_BUTTON_UNSPECIFIED0
CONTROL_BUTTON_BACK1
CONTROL_BUTTON_HOME2
CONTROL_BUTTON_RECENTS3
CONTROL_BUTTON_NOTIFICATIONS4Opens the notification shade.
CONTROL_BUTTON_POWER 5 Turns the screen off; with power-ups it also turns it back on.
CONTROL_BUTTON_VOLUME_UP6
CONTROL_BUTTON_VOLUME_DOWN7

message ButtonPress#

A press and release of one of the device's buttons.

FieldTypeNumberMeaning
buttonControlButton1

message ControlEvent#

One thing the viewer does.

FieldTypeNumberMeaning
pointerPointerInput1
keyferret.remote_input.v1.KeyEvent2
textferret.remote_input.v1.TextInput3
buttonButtonPress4

message ControlInput#

Sent by the viewer while control is allowed, in order. Expects no reply. The source drops it when control isn't allowed for this viewer, and takes at most 512 events from one batch.

FieldTypeNumberMeaning
eventsrepeated ControlEvent1

enum Codec#

How the pictures are encoded.

ValueNumberMeaning
CODEC_UNSPECIFIED0
CODEC_H264 1 H.264 video. Frame.data is one access unit in Annex-B form.
CODEC_JPEG 2 A JPEG picture per frame, for viewers without a video decoder. Fewer frames per second and a smaller picture.

enum AudioCodec#

How the source's sound is encoded.

ValueNumberMeaning
AUDIO_CODEC_UNSPECIFIED0
AUDIO_CODEC_OPUS 1 Opus, timed at 48 kHz. AudioFrame.data is one Opus packet.
AUDIO_CODEC_PCM_S16LE 2 Signed 16-bit little-endian samples, channels interleaved, for viewers without an Opus decoder.

message StartRequest#

Asks the source to show its screen. Expects a StartPending or StartDeny reply. After StartPending, the source sends StartAccept or StartDeny later, without expecting a reply.

FieldTypeNumberMeaning
version uint32 1 The version of these messages the viewer speaks.
codecs repeated Codec 2 What the viewer can decode, best first.
max_width uint32 3 The largest picture the viewer wants, in pixels. 0 leaves it to the source, which never sends more than 1920 on the long side.
max_heightuint324
max_fps uint32 5 0 leaves it to the source.
audio_codecs repeated AudioCodec 6 What the viewer can play of the source's sound, best first. Empty asks for pictures only.

message StartPending#

The source is asking its owner. The answer follows as StartAccept or StartDeny.

FieldTypeNumberMeaning
timeout_seconds uint32 1 How long the source waits for its owner before it denies with DENY_REASON_TIMEOUT.

message StartAccept#

The owner said yes. A StreamConfig and Frames follow until either side sends Stop.

FieldTypeNumberMeaning
version uint32 1 The version of these messages the source speaks.
codec Codec 2 The codec the source picked from StartRequest.codecs.
audio AudioAnswer 3 Whether sound comes with the pictures, for a viewer that asked.
audio_codec AudioCodec 4 With AUDIO_ANSWER_SENDING : the codec the source picked from StartRequest.audio_codecs .

enum AudioAnswer#

What a source says to a viewer that asked for sound. Only what plays on the source is ever sent, never its microphone, and only while its screen is shown.

ValueNumberMeaning
AUDIO_ANSWER_UNSPECIFIED 0 The source doesn't know about sound (an older build), or wasn't asked.
AUDIO_ANSWER_SENDING 1 An AudioConfig and AudioFrames follow.
AUDIO_ANSWER_OFF 2 The source's owner hasn't turned sending sound on.
AUDIO_ANSWER_UNSUPPORTED 3 The source can't capture what it plays, or can't encode any of StartRequest.audio_codecs .

enum DenyReason#

Why a source said no.

ValueNumberMeaning
DENY_REASON_UNSPECIFIED0
DENY_REASON_DENIED1Its owner said no on the system prompt.
DENY_REASON_TIMEOUT2Nobody answered on the source in time.
DENY_REASON_BUSY 3 It already shares its screen, or is asking its owner, for another device.
DENY_REASON_UNSUPPORTED 4 This device can't capture its screen.
DENY_REASON_TURNED_OFF 5 Its owner turned screen mirroring off.
DENY_REASON_VERSION6The viewer speaks a newer version.
DENY_REASON_NO_CODEC 7 The source can't encode any of StartRequest.codecs.
DENY_REASON_CANNOT_ASK 8 The source couldn't show the question, such as when its app is in the background and may not post notices.
DENY_REASON_FAILED9Capturing or encoding failed to start.

message StartDeny#

FieldTypeNumberMeaning
reasonDenyReason1

message StreamConfig#

How to decode the frames that follow. The source sends it before the first frame, and again with a new config_id when the picture changes, such as when the phone is rotated.

FieldTypeNumberMeaning
config_id uint32 1 Goes up by one with every new config in a mirroring session.
codecCodec2
width uint32 3 Size of the picture in pixels, as it should be shown.
heightuint324
rotation uint32 5 How the source's screen is rotated, in degrees clockwise: 0, 90, 180 or 270. The picture is already upright; this is for information.
fps uint32 6 The most frames per second the source sends.
sps bytes 7 H.264 only: the sequence and picture parameter sets, each one NAL unit without a start code.
ppsbytes8

message Frame#

One picture. Sent without expecting a reply.

FieldTypeNumberMeaning
config_id uint32 1 The StreamConfig this frame belongs to. A viewer drops frames of a config it hasn't seen.
sequence uint64 2 Goes up by one with every frame the source produced, including those it dropped, so a gap tells the viewer how many were dropped.
pts_us int64 3 When the picture was captured, in microseconds on the source's own clock. Only differences mean something.
keyframe bool 4 The frame decodes on its own. After a gap, a viewer waits for one.
data bytes 5 H.264: one access unit in Annex-B form. JPEG: the picture.

message AudioConfig#

How to play the sound that follows. The source sends it before the first AudioFrame, and again after a viewer came back from a dropped connection.

FieldTypeNumberMeaning
codecAudioCodec1
sample_rate uint32 2 Samples per second of each channel.
channels uint32 3 1 or 2. With two, samples are interleaved left then right.

message AudioFrame#

A few milliseconds of what plays on the source. Sent without expecting a reply. Apps on the source that don't allow their sound to be captured are simply not in it, and nothing is sent while the source is silent.

FieldTypeNumberMeaning
sequence uint64 1 Goes up by one with every frame the source produced, including those it dropped because the connection backed up.
pts_us int64 2 When the sound was captured, in microseconds on the same clock as Frame.pts_us , so a viewer can keep sound and picture together.
data bytes 3 Opus: one packet. PCM: whole samples for every channel.

message AudioEnded#

The source's sound stopped, such as when capturing it failed. The pictures go on. Sent without expecting a reply.

message KeyframeRequest#

The viewer lost its place, such as after a decoding error, and asks for a frame that decodes on its own. Sent without expecting a reply.

enum StopReason#

Why mirroring ended.

ValueNumberMeaning
STOP_REASON_UNSPECIFIED0
STOP_REASON_VIEWER_DONE 1 The viewer is done, such as when its mirror page closed, or it gave up waiting for the answer.
STOP_REASON_STOPPED_ON_SOURCE 2 Someone on the source pressed Stop.
STOP_REASON_SYSTEM_ENDED 3 The source's system ended the capture, such as when the phone was locked.
STOP_REASON_TURNED_OFF 4 The source's owner turned screen mirroring off.
STOP_REASON_FAILED5Capturing or encoding stopped working.
STOP_REASON_NOT_MIRRORING 6 A frame or request arrived for a mirroring session that isn't running.

message Stop#

Ends mirroring. Either side sends it, without expecting a reply. The source stops capturing at once.

FieldTypeNumberMeaning
reasonStopReason1

message SourceState#

Something about the source's screen changed while it is shared.

FieldTypeNumberMeaning
screen_off bool 1 The screen is off: no new frames until it is on again.

message Stats#

How the stream is doing. The viewer sends one about every second; the source answers each with its own, and uses them to pick the bitrate.

FieldTypeNumberMeaning
sent_at_ms int64 1 When this was sent, in milliseconds on the sender's own clock.
echo_sent_at_ms int64 2 Source only: sent_at_ms of the viewer's Stats this answers, so the viewer can measure the round trip.
fps uint32 3 Viewer: frames shown in the last second. Source: frames sent.
dropped_frames uint32 4 Frames dropped in the last second: by the source because the connection backed up, or by the viewer because decoding fell behind.
bitrate_kbps uint32 5 Source only: what the encoder aims for right now, in kilobits per second. 0 for JPEG.

ferret.notifications.v1#

message NotificationAction#

A button on a notification, such as "Reply" or "Mark as read".

FieldTypeNumberMeaning
id string 1 Chosen by the source device; send it back in InvokeAction.
titlestring2
is_reply bool 3 The action takes typed text, such as a message reply.

message NotificationItem#

One notification shown on the source device (a phone).

FieldTypeNumberMeaning
key string 1 The source's own key for it. Posting the same key again updates it.
app_package string 2 The app that posted it, such as "org.thoughtcrime.securesms".
app_namestring3
titlestring4
textstring5
posted_at_ms int64 6 When the source posted it, in the source device's clock.
app_icon_png bytes 7 A small PNG of the app's icon. Empty when it was already sent for this app during the current session; receivers keep the last one per app.
is_conversation bool 8 A message in a conversation, such as a chat.
actionsrepeated NotificationAction9
text_hidden bool 10 The source held back the text (and a title that carried it) because it looks like a one-time code, such as a sign-in or bank code. Receivers say so instead of showing an empty line.

message NotificationPosted#

A new or updated notification. Sent without expecting a reply, only for notifications posted after the session opened.

FieldTypeNumberMeaning
notificationNotificationItem1

message NotificationRemoved#

The notification with key is gone on the source. Sent without expecting a reply.

FieldTypeNumberMeaning
keystring1

message CatchUp#

Sent by the source right after a session opens, instead of replaying what happened while the receiver was away.

FieldTypeNumberMeaning
missed_count uint32 1 Notifications posted while the receiver was away and still showing.
active_keys repeated string 2 Keys of notifications sent earlier that are still showing on the source. Receivers drop the ones not listed.
missed_app_names repeated string 3 Names of the apps the missed notifications came from, without repeats.

message InvokeAction#

Asks the source to run an action of a notification. Expects an InvokeActionResult reply.

FieldTypeNumberMeaning
keystring1
action_idstring2
reply_text string 3 The typed text for a reply action.

message InvokeActionResult#

FieldTypeNumberMeaning
okbool1

message DismissNotification#

Dismisses the notification with key on the source. Sent without expecting a reply; the source answers with NotificationRemoved once it is gone.

FieldTypeNumberMeaning
keystring1

enum AppFilter#

Which apps the source mirrors.

ValueNumberMeaning
APP_FILTER_UNSPECIFIED 0 Sent by sources that predate the filter: they mirror allowed_packages only, as APP_FILTER_ONLY .
APP_FILTER_ALL1Every app.
APP_FILTER_ALL_EXCEPT 2 Every app except excluded_packages.
APP_FILTER_ONLY3Only allowed_packages.

message MirrorSettings#

How the source mirrors notifications.

FieldTypeNumberMeaning
enabled bool 1 The person turned mirroring on.
access_granted bool 2 The platform lets the source read notifications.
skip_while_using bool 3 Mirroring pauses while the source is in use (screen on and unlocked).
allowed_packages repeated string 4 The apps picked for APP_FILTER_ONLY . Kept while another filter is active, so switching back restores them.
app_filter AppFilter 5 Which apps are mirrored.
excluded_packages repeated string 6 The apps muted for APP_FILTER_ALL_EXCEPT. Kept while another filter is active.

message MirrorSettingsRequest#

Asks the source for its MirrorSettings. Expects a MirrorSettings reply.

message AppEntry#

An app the person can pick in the app list.

FieldTypeNumberMeaning
packagestring1
namestring2
icon_png bytes 3 A small PNG of the app's icon.
allowed bool 4 Its notifications are mirrored under the current filter.
is_messaging bool 5 A messaging app, such as Signal or WhatsApp.
last_posted_ms int64 6 When the app last posted a notification the source saw, in the source device's clock. 0 when unknown.

message AppListRequest#

Asks the source for its apps. Expects an AppListResponse reply.

message AppListResponse#

FieldTypeNumberMeaning
appsrepeated AppEntry1

message AppChoice#

Turns one app on or off: under APP_FILTER_ALL_EXCEPT it changes excluded_packages, under APP_FILTER_ONLY allowed_packages. Turning an app off under APP_FILTER_ALL switches to APP_FILTER_ALL_EXCEPT.

FieldTypeNumberMeaning
packagestring1
allowedbool2

message UpdateMirrorSettings#

Changes the source's settings. Expects a MirrorSettings reply.

FieldTypeNumberMeaning
appsrepeated AppChoice1
skip_while_using optional bool 2 Left out to keep the current value.
app_filter optional AppFilter 3 Applied before apps. Left out to keep the current filter.

ferret.photos.v1#

enum PhotoKind#

What a photo is.

ValueNumberMeaning
PHOTO_KIND_UNSPECIFIED0
PHOTO_KIND_PHOTO1
PHOTO_KIND_SCREENSHOT 2 A screenshot or screen recording still, as the phone files it.
PHOTO_KIND_VIDEO3

enum PhotoAccess#

How much the asking device may see right now.

ValueNumberMeaning
PHOTO_ACCESS_UNSPECIFIED0
PHOTO_ACCESS_NOT_ALLOWED 1 The phone's owner hasn't let the asking device see photos.
PHOTO_ACCESS_NO_PERMISSION 2 The phone's system hasn't given Ferret photo access yet, or it was turned off.
PHOTO_ACCESS_LIMITED 3 Only the photos the owner picked: Android 14's "Selected photos" or the iPhone's limited library.
PHOTO_ACCESS_FULL4
PHOTO_ACCESS_UNAVAILABLE 5 The phone can't read photos right now, such as an iPhone with Ferret in the background.

message PhotoItem#

One photo or video on the phone. Ids are opaque and only mean something to the phone that sent them.

FieldTypeNumberMeaning
idstring1
taken_at_ms int64 2 When it was taken (or added), in milliseconds since the Unix epoch.
widthuint323
heightuint324
kindPhotoKind5
sizeuint646Bytes, or 0 when unknown.
name string 7 The file name on the phone, such as "IMG_2041.jpg".
duration_msuint328Videos only.

message PhotoListRequest#

Asks for a page of photos, newest first (a request, answered with PhotoList).

FieldTypeNumberMeaning
cursor string 1 Empty for the first page, else the previous page's next_cursor.
limit uint32 2 At most this many; the phone may send fewer and caps it at 200.

message PhotoList#

FieldTypeNumberMeaning
itemsrepeated PhotoItem1
next_cursor string 2 Empty when this was the last page.
accessPhotoAccess3
total uint32 4 How many photos the asking device can see in all, or 0 when unknown.

message ThumbnailRequest#

Asks for a small JPEG of one photo (a request, answered with Thumbnail).

FieldTypeNumberMeaning
idstring1
max_px uint32 2 The longest side, in pixels. The phone caps it at 2048.

message Thumbnail#

FieldTypeNumberMeaning
idstring1
jpeg bytes 2 Empty when the photo is gone or the access changed; see access.
accessPhotoAccess3

message PhotoFetchRequest#

Asks the phone to send these photos' full files through drop (a request, answered with PhotoFetchReply). The asking device accepts that transfer on its own: it asked for it.

FieldTypeNumberMeaning
idsrepeated string1

message PhotoFetchReply#

FieldTypeNumberMeaning
transfer_id string 1 The drop transfer that carries the files, or empty when none could be sent.
accessPhotoAccess2
missing uint32 3 How many of the asked ids weren't found any more.

message ScreenshotSubscription#

Tells the phone whether the sender wants new screenshots sent to it as soon as they are taken, while Ferret runs. Sent again after each reconnect; the phone forgets it when the session ends. No reply.

FieldTypeNumberMeaning
enabledbool1

message ScreenshotSent#

The phone is sending a new screenshot through drop. Sent just before that transfer's offer. No reply.

FieldTypeNumberMeaning
transfer_idstring1
itemPhotoItem2

message PhotoAccessPrompt#

Asks the phone's owner to share photos with the sender, or more of them. The phone shows a notice; nothing changes until its owner acts. No reply.

ferret.remote_input.v1#

message ControlRequest#

Asks the computer for control. Expects a ControlPending, ControlGrant or ControlDeny reply. After ControlPending, the computer sends the ControlGrant or ControlDeny later, without expecting a reply.

FieldTypeNumberMeaning
version uint32 1 The version of these messages the controller speaks.

message ControlPending#

The computer is asking its owner. The answer follows as ControlGrant or ControlDeny.

FieldTypeNumberMeaning
timeout_seconds uint32 1 How long the computer waits for its owner before it denies with DENY_REASON_TIMEOUT.

message ControlGrant#

The controller may send InputBatches until either side sends ControlStop.

FieldTypeNumberMeaning
version uint32 1 The version of these messages the computer speaks.
always bool 2 The computer's owner allowed this device for good, not just this once.

enum DenyReason#

Why a computer said no.

ValueNumberMeaning
DENY_REASON_UNSPECIFIED0
DENY_REASON_DENIED1Its owner said no.
DENY_REASON_TIMEOUT2Nobody answered on the computer in time.
DENY_REASON_BUSY 3 Another device controls it, or asks to, right now.
DENY_REASON_NEEDS_PERMISSION 4 The system permission to control input is missing, such as Accessibility on macOS. The computer shows its owner how to allow it.
DENY_REASON_UNSUPPORTED 5 This computer has no way to inject input, such as Linux without uinput access, xdotool or ydotool.
DENY_REASON_TURNED_OFF6Its owner turned remote input off.
DENY_REASON_VERSION 7 The controller speaks a newer major version.

message ControlDeny#

FieldTypeNumberMeaning
reasonDenyReason1

enum StopReason#

Why control ended.

ValueNumberMeaning
STOP_REASON_UNSPECIFIED0
STOP_REASON_CONTROLLER_DONE 1 The controller is done, such as when its touchpad page closed.
STOP_REASON_STOPPED_ON_HOST 2 Someone on the computer pressed Stop.
STOP_REASON_IDLE3Nothing happened for a long time.
STOP_REASON_REVOKED 4 The computer's owner revoked this device, or turned remote input off.
STOP_REASON_NOT_CONTROLLING 5 Input arrived from a device that has no control right now.
STOP_REASON_FAILED 6 The computer can no longer inject input, such as when its owner turned Accessibility access off.

message ControlStop#

Ends control. Either side sends it, without expecting a reply. The computer releases every button and key still held.

FieldTypeNumberMeaning
reasonStopReason1

enum MouseButton#

A pointer button.

ValueNumberMeaning
MOUSE_BUTTON_UNSPECIFIED0
MOUSE_BUTTON_LEFT1
MOUSE_BUTTON_RIGHT2
MOUSE_BUTTON_MIDDLE3

enum Key#

A key, by what it is rather than by any platform's code. Text goes as TextInput; keys are for shortcuts and keys that type nothing.

ValueNumberMeaning
KEY_UNSPECIFIED0
KEY_ENTER1
KEY_BACKSPACE2
KEY_DELETE3
KEY_TAB4
KEY_ESCAPE5
KEY_SPACE6
KEY_ARROW_LEFT7
KEY_ARROW_RIGHT8
KEY_ARROW_UP9
KEY_ARROW_DOWN10
KEY_HOME11
KEY_END12
KEY_PAGE_UP13
KEY_PAGE_DOWN14
KEY_MEDIA_PLAY_PAUSE20
KEY_MEDIA_NEXT21
KEY_MEDIA_PREVIOUS22
KEY_VOLUME_UP23
KEY_VOLUME_DOWN24
KEY_VOLUME_MUTE25
KEY_F131
KEY_F232
KEY_F333
KEY_F434
KEY_F535
KEY_F636
KEY_F737
KEY_F838
KEY_F939
KEY_F1040
KEY_F1141
KEY_F1242
KEY_A65Letters and digits, for shortcuts such as Ctrl+C.
KEY_B66
KEY_C67
KEY_D68
KEY_E69
KEY_F70
KEY_G71
KEY_H72
KEY_I73
KEY_J74
KEY_K75
KEY_L76
KEY_M77
KEY_N78
KEY_O79
KEY_P80
KEY_Q81
KEY_R82
KEY_S83
KEY_T84
KEY_U85
KEY_V86
KEY_W87
KEY_X88
KEY_Y89
KEY_Z90
KEY_DIGIT_0100
KEY_DIGIT_1101
KEY_DIGIT_2102
KEY_DIGIT_3103
KEY_DIGIT_4104
KEY_DIGIT_5105
KEY_DIGIT_6106
KEY_DIGIT_7107
KEY_DIGIT_8108
KEY_DIGIT_9109

enum Modifier#

A key held with another key. MODIFIER_META is Command on macOS, the Windows key on Windows and Super on Linux.

ValueNumberMeaning
MODIFIER_UNSPECIFIED0
MODIFIER_SHIFT1
MODIFIER_CONTROL2
MODIFIER_ALT3
MODIFIER_META4

message PointerMove#

Moves the pointer by a distance in logical pixels of the computer's screen, after the controller applied its speed and acceleration.

FieldTypeNumberMeaning
dxsint321
dysint322

message ButtonEvent#

Presses (pressed) or releases a pointer button. A click is a press and a release; a drag is a press, moves, then a release.

FieldTypeNumberMeaning
buttonMouseButton1
pressedbool2

message Scroll#

Scrolls by a distance in logical pixels. Positive dy scrolls toward the end of the page (down), positive dx to the right.

FieldTypeNumberMeaning
dxsint321
dysint322

message KeyEvent#

Presses (pressed) or releases a key, with the modifiers held for it.

FieldTypeNumberMeaning
keyKey1
pressedbool2
modifiersrepeated Modifier3

message TextInput#

Types text as it is, whatever the computer's keyboard layout.

FieldTypeNumberMeaning
textstring1

message InputEvent#

One input action.

FieldTypeNumberMeaning
movePointerMove1
buttonButtonEvent2
scrollScroll3
keyKeyEvent4
textTextInput5

message InputBatch#

Input from the controller, in order, without expecting a reply. The controller sends at most about 60 a second and merges pointer moves in between, so a batch holds what happened since the last one.

FieldTypeNumberMeaning
eventsrepeated InputEvent1

message LockRequest#

Asks the computer to lock its screen now, as its own Lock Screen command does. Send it only to a computer whose FeatureSupport flags for this feature include "lock"; older computers don't know it. Expects a LockReply. The first time per device the computer asks its owner, so the reply can take as long as its consent timeout (60 seconds).

enum LockResult#

What came of a LockRequest.

ValueNumberMeaning
LOCK_RESULT_UNSPECIFIED0
LOCK_RESULT_LOCKED1The screen is locked.
LOCK_RESULT_DENIED2Its owner said no.
LOCK_RESULT_TIMEOUT3Nobody answered on the computer in time.
LOCK_RESULT_BUSY 4 The computer is asking its owner about another device right now.
LOCK_RESULT_TURNED_OFF5Its owner turned remote input off.
LOCK_RESULT_FAILED6The computer tried and couldn't lock.

message LockReply#

FieldTypeNumberMeaning
resultLockResult1

ferret.scripting.v1#

message ScriptNotice#

A short notice a script on the sending computer wants shown on the receiving device, from ferret-cli notify. Expects a ScriptNoticeReply. The receiver shows it only when its owner allowed scripts from the sending device (off by default), and drops floods.

FieldTypeNumberMeaning
title string 1 At most 120 characters; longer is cut.
body string 2 At most 500 characters; longer is cut.

message ScriptNoticeReply#

What came of a ScriptNotice.

FieldTypeNumberMeaning
resultScriptNoticeResult1

enum ScriptNoticeResult#

ValueNumberMeaning
SCRIPT_NOTICE_RESULT_UNSPECIFIED0
SCRIPT_NOTICE_RESULT_SHOWN1The receiver showed it.
SCRIPT_NOTICE_RESULT_NOT_ALLOWED 2 Its owner hasn't allowed scripts from the sending device to notify.
SCRIPT_NOTICE_RESULT_TOO_MANY 3 Too many notices came in a short time, so this one was dropped.
SCRIPT_NOTICE_RESULT_EMPTY4It had no title and no body.

ferret.v1#

enum Platform#

The operating system a device runs.

ValueNumberMeaning
PLATFORM_UNSPECIFIED0
PLATFORM_ANDROID1
PLATFORM_IOS2
PLATFORM_MACOS3
PLATFORM_LINUX4
PLATFORM_WINDOWS5
PLATFORM_BROWSER6
PLATFORM_CLI7

enum FormFactor#

The kind of device, used for icons and for choosing where to suggest things.

ValueNumberMeaning
FORM_FACTOR_UNSPECIFIED0
FORM_FACTOR_PHONE1
FORM_FACTOR_TABLET2
FORM_FACTOR_LAPTOP3
FORM_FACTOR_DESKTOP4
FORM_FACTOR_SERVER5

message DeviceInfo#

What a device says about itself after the secure channel is up.

FieldTypeNumberMeaning
id string 1 Stable id derived from the device's static public key (see spec/identity.md).
namestring2
platformPlatform3
form_factorFormFactor4
modelstring5
app_versionstring6
protocol_version uint32 7 Highest protocol version the device speaks.
oldest_protocol_version uint32 8 Lowest protocol version the device still speaks. Zero means the same as protocol_version. Two devices talk only while their ranges overlap; each side works out which one must update from the two ranges alone.

message FeatureSupport#

A feature a device offers, with the feature's own version.

FieldTypeNumberMeaning
id string 1 Feature id, such as "handoff" or "clipboard".
versionuint322
flags repeated string 3 Feature-specific flags, such as "send" and "receive".

message Announce#

Sent over UDP multicast so devices on the same network find each other. It carries no secrets: anyone on the network can read it.

FieldTypeNumberMeaning
protocol_versionuint321
device_idstring2
namestring3
platformPlatform4
form_factorFormFactor5
portuint326
reply bool 7 True when this is an answer to someone else's announce, so it is not answered again.

message Envelope#

Every message on a session is an envelope. Features own their payload types, so new features never change this file.

FieldTypeNumberMeaning
id uint64 1 Sender-chosen, unique per session, never 0.
reply_to uint64 2 The id of the request this answers, or 0.
feature string 3 Feature id, such as "session", "handoff" or "drop".
type string 4 Full protobuf name of the payload, such as "ferret.handoff.v1.Activity".
payloadbytes5
error Error 6 Set on a reply that failed instead of a payload.
expects_reply bool 7 The sender waits for a reply (an envelope with reply_to = id).

message Error#

FieldTypeNumberMeaning
codeErrorCode1
messagestring2

enum ErrorCode#

ValueNumberMeaning
ERROR_CODE_UNSPECIFIED0
ERROR_CODE_UNSUPPORTED1
ERROR_CODE_DENIED2
ERROR_CODE_INVALID3
ERROR_CODE_INTERNAL4
ERROR_CODE_TIMEOUT5
ERROR_CODE_CANCELLED6

message PairingOffer#

What a pairing QR code or link carries. Encoded as base64url in ferret://pair?o=.

FieldTypeNumberMeaning
protocol_versionuint321
device_idstring2
namestring3
platformPlatform4
hosts repeated string 5 Addresses the offering device listens on, such as "192.168.1.20".
portuint326
static_public_key bytes 7 X25519 static public key, 32 bytes. The scanner checks the Noise handshake's remote static key against it.
secret bytes 8 One-time secret, 16 bytes, proving the scanner saw this offer.
expires_at_msuint649
oldest_protocol_version uint32 10 The oldest protocol version the offering device still speaks; with protocol_version, the range a scanner must overlap to pair. Zero from builds before it: they speak protocol_version only.

message PairingRequest#

Sent by the device that wants to pair, first thing on a new channel (feature "pairing").

FieldTypeNumberMeaning
deviceDeviceInfo1
proof bytes 2 HMAC-SHA256(offer secret, handshake hash) when pairing from an offer. Empty when pairing by comparing codes.
commitment bytes 3 SHA-256 of the requester's nonce, when pairing by comparing codes. It fixes the nonce before the answerer picks its own, so neither side can steer the six digits (see PairingChallenge).
also_devices repeated string 4 Names of the requester's other devices, which the answerer will be connected to as well (see Introduce). Shown on the answerer's prompt.

message PairingChallenge#

Pairing by comparing codes, step 2: the answerer's 16-byte nonce, sent once it holds the requester's commitment (feature "pairing").

FieldTypeNumberMeaning
noncebytes1

message PairingReveal#

Pairing by comparing codes, step 3: the requester's 16-byte nonce, which must hash to its commitment (feature "pairing"). Both sides then show HMAC-SHA256(handshake hash, "ferret-compare" || requester nonce || answerer nonce) as six digits.

FieldTypeNumberMeaning
noncebytes1

message PairingConfirm#

Pairing by comparing codes: what the requester's user said after seeing the six digits (feature "pairing"). The answerer trusts the requester only after its own user agreed and this arrived with accepted = true.

FieldTypeNumberMeaning
acceptedbool1

message PairingResponse#

The answer to a PairingRequest (feature "pairing").

FieldTypeNumberMeaning
resultPairingResult1
deviceDeviceInfo2
proof bytes 3 HMAC-SHA256(offer secret, handshake hash || "response") so the scanner knows the offerer still holds the secret.

enum PairingResult#

ValueNumberMeaning
PAIRING_RESULT_UNSPECIFIED0
PAIRING_RESULT_ACCEPTED1
PAIRING_RESULT_REJECTED2
PAIRING_RESULT_EXPIRED3
PAIRING_RESULT_BAD_PROOF4
PAIRING_RESULT_TIMED_OUT5Nobody answered the prompt in time.

message Introduce#

Tells a paired device about the sender's other paired devices, so one pairing joins them all (feature "pairing", on a trusted session only). The session's Noise handshake proves who sends it; a device accepts it only from a device it already trusts, and only while its user lets pairings be shared. Devices that don't know the message ignore it.

FieldTypeNumberMeaning
devicesrepeated IntroducedDevice1
forgotten repeated ForgottenDevice 2 Devices the user removed from all their devices.

message IntroducedDevice#

One device the sender trusts.

FieldTypeNumberMeaning
id string 1 Must be the id derived from static_public_key, or the entry is dropped.
namestring2
platformPlatform3
form_factorFormFactor4
static_public_key bytes 5 X25519 static public key, 32 bytes. The receiver trusts exactly this key.
host string 6 Where the sender last reached the device, to connect without waiting for discovery. May be empty.
portuint327
paired_at_ms uint64 8 When the user paired the device, passed along unchanged. An entry older than the receiver's record of forgetting the device is dropped.

message ForgottenDevice#

A device to stop trusting, with when the user removed it.

FieldTypeNumberMeaning
idstring1
forgotten_at_msuint642

message Hello#

First envelope each side sends on a trusted session (feature "session").

FieldTypeNumberMeaning
deviceDeviceInfo1
featuresrepeated FeatureSupport2
listen_port uint32 3 TCP port this device accepts connections on, for reconnecting later.
vpn_addresses repeated string 4 This device's addresses on the user's own VPN (Tailscale, ZeroTier, WireGuard), such as "100.101.102.103". Sent only to a device that asked for them (see wants_vpn_addresses and VpnReach); empty otherwise, and from devices that predate VPN reach. An empty list never clears what the receiver remembers: VpnReach does that.
wants_vpn_addresses bool 5 The user turned on "Also reach this device over my VPN" here, so the receiver may share its VPN addresses with this device.

message VpnReach#

VPN reach changed during a session (feature "session"): the sender's switch for the receiver, and the sender's VPN addresses when the receiver asked for them. Devices that predate it ignore it.

FieldTypeNumberMeaning
wants_addresses bool 1 Same as Hello.wants_vpn_addresses.
includes_addresses bool 2 Whether addresses below is the sender's full list. False when the receiver hasn't asked for them, and then addresses is empty.
addressesrepeated string3

message Ping#

Keeps a session alive and measures round trips (feature "session").

FieldTypeNumberMeaning
sent_at_msuint641

message Pong#

FieldTypeNumberMeaning
ping_sent_at_msuint641

message Presence#

Says the user is active on this device right now, so others know where to show suggestions (feature "session").

FieldTypeNumberMeaning
user_activebool1
screen_onbool2
battery_percent int32 3 Battery level 0-100, or -1 when unknown or plugged desktop.
chargingbool4
away bool 5 A computer whose screen is locked or showing another account: this device is connected, but nobody is at it to see what arrives.

message Goodbye#

Sent before a side closes on purpose, so the other one doesn't reconnect.

FieldTypeNumberMeaning
reasonGoodbyeReason1

enum GoodbyeReason#

ValueNumberMeaning
GOODBYE_REASON_UNSPECIFIED0
GOODBYE_REASON_SHUTDOWN1
GOODBYE_REASON_UNPAIRED2
GOODBYE_REASON_DUPLICATE3

message WakeInfo#

How to wake a computer from sleep with a Wake-on-LAN magic packet. A computer shares it only with its paired devices (feature "wake"), when a session opens and again when its network cards change. A MAC address identifies the computer, so it never goes anywhere else.

FieldTypeNumberMeaning
interfaces repeated WakeInterface 1 Its wired and Wi-Fi network cards that have an IPv4 address, wired first. Virtual cards (VPNs, bridges, containers) are left out.

message WakeInterface#

One network card a computer can be woken through.

FieldTypeNumberMeaning
mac bytes 1 Hardware (MAC) address, 6 bytes.
address string 2 Its IPv4 address on that network, such as "192.168.1.20".
broadcast string 3 That network's broadcast address, such as "192.168.1.255".
linkWakeLink4
setting WakeSetting 5 Whether the card is set to wake on a magic packet, when the computer can tell.

How a network card is connected. Wired cards wake reliably once Wake-on-LAN is on; few Wi-Fi cards wake at all.

ValueNumberMeaning
WAKE_LINK_UNSPECIFIED0
WAKE_LINK_WIRED1
WAKE_LINK_WIFI2

enum WakeSetting#

What the computer's own settings say about waking on a magic packet.

ValueNumberMeaning
WAKE_SETTING_UNSPECIFIED 0 It couldn't tell, such as without permission to ask the driver.
WAKE_SETTING_ON1
WAKE_SETTING_OFF2

ferret.wake.v1#

message WakeRequest#

Asks a device that is on to send the magic packet for another of the user's devices, for when the asking one can't reach that network itself (an iPhone may not broadcast, a phone may be on mobile data). Expects a WakeReply. The receiver acts only for a device it is paired with too.

FieldTypeNumberMeaning
device_idstring1The device to wake.
info ferret.v1.WakeInfo 2 What the asking device knows about how to wake it. The receiver uses its own copy first.
last_address string 3 The address the asking device last reached it at, such as "192.168.1.20".

message WakeReply#

What came of a WakeRequest.

FieldTypeNumberMeaning
resultWakeResult1

enum WakeResult#

ValueNumberMeaning
WAKE_RESULT_UNSPECIFIED0
WAKE_RESULT_SENT 1 The magic packet went out. Whether the device wakes shows when it connects.
WAKE_RESULT_NOT_PAIRED 2 The receiver isn't paired with that device, so it won't wake it.
WAKE_RESULT_RELAY_OFF 3 Its owner turned off waking devices for others on the receiver.
WAKE_RESULT_NO_INFO 4 Neither side knows the device's network card.
WAKE_RESULT_FAILED5Sending failed, such as with no network.