Merge 62425cce00 into 92b109b933

README.md

@@ -12,3 +12,7 @@ through an Arduino micro running a keyer program.
 This program is on github as [vail-adapter](https://github.com/nealey/vail-adapter),
 or [in Arduino Create](https://create.arduino.cc/editor/neale/f94bb765-47bd-4bc4-9cbf-b978f7124bdc).
 
+More Documentation
+-------
+
+* [Vail Protocol](docs/protocol.md)

docs/protocol.md

@@ -0,0 +1,94 @@
+The Vail Protocol
+=============
+
+Vail messages can be encoded with JSON or marshaled into a "binary" format.
+
+Go Definition
+--------------------
+
+```go
+type Message struct {
+	// Timestamp of this message. Milliseconds since epoch.
+	Timestamp int64
+
+	// Message timing in milliseconds.
+	// Timings alternate between tone and silence.
+	// For example, `A` could be sent as [80, 80, 240]
+	Duration []uint16
+}
+```
+
+JSON
+-------
+
+JSON-encoded Vail messages are a direct encoding of the struct:
+
+```json
+{
+    "Timestamp": 1702846980,
+    "Duration": [80, 80, 240]
+}
+```
+
+This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
+
+
+Binary Marshalling
+---------------------
+
+The binary marshalled version of a Vail message is encoded big-endian:
+
+    00 00 00 00 65 7f 62 04   00 50 00 50 00 f0
+
+Is decoded as:
+
+* Timestamp (int64): `00 00 00 00 65 7f 62 04` = 1702846980
+* Duration ([]uint16):
+  * `00 50` = 80
+  * `00 50` = 80
+  * `00 f0` = 240
+
+This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
+
+
+WebSockets
+==========
+
+The reference Vail server accepts WebSockets communications to the path `/chat`,
+with the channel sent as the 'repeater' query parameter.
+
+For instance, the "Example" channel is
+wss://vail.woozle.org/chat?repeater=Example
+
+The WebSockets subprotocol may be either:
+
+* `json.vail.woozle.org` for JSON packets
+* `binary.vail.woozle.org` for binary marshalled packets
+
+
+Practical Considerations
+==================
+
+I am a network protocol designer:
+Vail was designed to contend with
+Internet latency and jitter.
+It relies heavily on an accurate Real-Time Clock on each client.
+
+Playback Delay
+------------------
+
+Clients should implement a delay on playback of all recieved messages,
+to allow for network latency and jitter.
+
+I have found that a 2-second delay is usually enough, but people on very high-latency links may need a larger delay.
+
+If the timestamp + delay on a recieved packet is after the current time of day,
+it may be appropriate to increase the delay.
+
+Clock skew
+---------------
+
+On connecting,
+clients will recieve a packet with no Durations.
+Clients should use this timestamp
+to estimate skew between the client and server's clock.

static/scripts/fortunes.mjs

@@ -39,7 +39,6 @@ export const fortunes = [
 	"A day for firm decisions!  Or is it?",
 	"A few hours grace before the madness begins again.",
 	"A gift of a flower will soon be made to you.",
-	"A long-forgotten loved one will appear soon. Buy the negatives at any price.",
 	"A tall, dark stranger will have more fun than you.",
 	"A visit to a fresh place will bring strange work.",
 	"A visit to a strange place will bring fresh work.",
@@ -48,8 +47,6 @@ export const fortunes = [
 	"Accent on helpful side of your nature.  Drain the moat.",
 	"Advancement in position.",
 	"After your lover has gone you will still have PEANUT BUTTER!",
-	"Afternoon very favorable for romance.  Try a single person for a change.",
-	"Alimony and bribes will engage a large share of your wealth.",
 	"All the troubles you have will pass away very quickly.",
 	"Among the lucky, you are the chosen one.",
 	"An avocado-tone refrigerator would look good on your resume.",
@@ -61,18 +58,15 @@ export const fortunes = [
 	"Are you sure the back door is locked?",
 	"Artistic ventures highlighted.  Rob a museum.",
 	"Avert misunderstanding by calm, poise, and balance.",
-	"Avoid gunfire in the bathroom tonight.",
 	"Avoid reality at all costs.",
 	"Bank error in your favor.  Collect $200.",
 	"Be careful!  Is it classified?",
-	"Be careful!  UGLY strikes 9 out of 10!",
 	"Be cautious in your daily affairs.",
 	"Be cheerful while you are alive. -- Phathotep, 24th Century B.C.",
 	"Be different: conform.",
 	"Be free and open and breezy!  Enjoy!  Things won't get any better so get used to it.",
 	"Be security conscious -- National defense is at stake.",
 	"Beauty and harmony are as necessary to you as the very breath of life.",
-	"Best of all is never to have been born.  Second best is to die soon.",
 	"Better hope the life-inspector doesn't come around while you have your life in such a mess.",
 	"Beware of a dark-haired man with a loud tie.",
 	"Beware of a tall black man with one blond shoe.",
@@ -80,8 +74,6 @@ export const fortunes = [
 	"Beware of Bigfoot!",
 	"Beware of low-flying butterflies.",
 	"Beware the one behind you.",
-	"Blow it out your ear.",
-	"Break into jail and claim police brutality.",
 	"Bridge ahead.  Pay troll.",
 	"Caution: breathing may be hazardous to your health.",
 	"Caution: Keep out of reach of children.",
@@ -98,7 +90,6 @@ export const fortunes = [
 	"Do not overtax your powers.",
 	"Do not sleep in a eucalyptus tree tonight.",
 	"Do nothing unless you must, and when you must act -- hesitate.",
-	"Do something unusual today.  Pay a bill.",
 	"Do what comes naturally.  Seethe and fume and throw a tantrum.",
 	"Domestic happiness and faithful friends.",
 	"Don't feed the bats tonight.",
@@ -111,7 +102,6 @@ export const fortunes = [
 	"Don't look back, the lemmings are gaining on you.",
 	"Don't look now, but the man in the moon is laughing at you.",
 	"Don't look now, but there is a multi-legged creature on your shoulder.",
-	"Don't plan any hasty moves.  You'll be evicted soon anyway.",
 	"Don't read any sky-writing for the next two weeks.",
 	"Don't read everything you believe.",
 	"Don't relax!  It's only your tension that's holding you together.",
@@ -123,7 +113,6 @@ export const fortunes = [
 	"Everything that you know is wrong, but you can be straightened out.",
 	"Everything will be just tickety-boo today.",
 	"Excellent day for putting Slinkies on an escalator.",
-	"Excellent day to have a rotten day.",
 	"Excellent time to become a missing person.",
 	"Executive ability is prominent in your make-up.",
 	"Exercise caution in your daily affairs.",
@@ -135,15 +124,11 @@ export const fortunes = [
 	"Generosity and perfection are your everlasting goals.",
 	"Give him an evasive answer.",
 	"Give thought to your reputation.  Consider changing name and moving to a new town.",
-	"Give your very best today.  Heaven knows it's little enough.",
 	"Go to a movie tonight.  Darkness becomes you.",
 	"Good day for a change of scene.  Repaper the bedroom wall.",
 	"Good day for overcoming obstacles.  Try a steeplechase.",
-	"Good day to deal with people in high places; particularly lonely stewardesses.",
-	"Good day to let down old friends who need help.",
 	"Good news from afar can bring you a welcome visitor.",
 	"Good news.  Ten weeks from Friday will be a pretty good day.",
-	"Good night to spend with family, but avoid arguments with your mate's new lover.",
 	"Green light in A.M. for new projects.  Red light in P.M. for traffic tickets.",
 	"Hope that the day after you die is a nice day.",
 	"If you can read this, you're too close.",
@@ -153,7 +138,6 @@ export const fortunes = [
 	"If you think last Tuesday was a drag, wait till you see what happens tomorrow!",
 	"If your life was a horse, you'd have to shoot it.",
 	"In the stairway of life, you'd best take the elevator.",
-	"Increased knowledge will help you now.  Have mate's phone bugged.",
 	"Is that really YOU that is reading this?",
 	"Is this really happening?",
 	"It may or may not be worthwhile, but it still has to be done.",
@@ -190,7 +174,6 @@ export const fortunes = [
 	"Ships are safe in harbor, but they were never meant to stay there.",
 	"Slow day.  Practice crawling.",
 	"Snow Day -- stay home.",
-	"So this is it.  We're going to die.",
 	"So you're back... about time...",
 	"Someone is speaking well of you.",
 	"Someone is speaking well of you. How unusual!",
@@ -208,7 +191,6 @@ export const fortunes = [
 	"Think twice before speaking, but don't say \"think think click click\".",
 	"This life is yours.  Some of it was given to you; the rest, you made yourself.",
 	"This will be a memorable month -- no matter how hard you try to forget it.",
-	"Time to be aggressive.  Go after a tattooed Virgo.",
 	"Today is National Existential Ennui Awareness Day.",
 	"Today is the first day of the rest of the mess.",
 	"Today is the first day of the rest of your life.",
@@ -220,9 +202,7 @@ export const fortunes = [
 	"Tomorrow, you can be anywhere.",
 	"Tonight you will pay the wages of sin; Don't forget to leave a tip.",
 	"Tonight's the night: Sleep in a eucalyptus tree.",
-	"Troubled day for virgins over 16 who are beautiful and wealthy and live in eucalyptus trees.",
 	"Truth will out this morning.  (Which may really mess things up.)",
-	"Try the Moo Shu Pork.  It is especially good today.",
 	"Try to get all of your posthumous medals in advance.",
 	"Try to have as good a life as you can under the circumstances.",
 	"Try to value useful qualities in one who loves you.",
@@ -244,38 +224,29 @@ export const fortunes = [
 	"You are fairminded, just and loving.",
 	"You are farsighted, a good planner, an ardent lover, and a faithful friend.",
 	"You are fighting for survival in your own sweet and gentle way.",
-	"You are going to have a new love affair.",
 	"You are magnetic in your bearing.",
 	"You are not dead yet.  But watch for further reports.",
 	"You are number 6!  Who is number one?",
 	"You are only young once, but you can stay immature indefinitely.",
 	"You are scrupulously honest, frank, and straightforward.  Therefore you have few friends.",
-	"You are sick, twisted and perverted.  I like that in a person.",
 	"You are so boring that when I see you my feet go to sleep.",
 	"You are standing on my toes.",
 	"You are taking yourself far too seriously.",
 	"You are the only person to ever get this message.",
 	"You are wise, witty, and wonderful, but you spend too much time reading this sort of trash.",
-	"You attempt things that you do not even plan because of your extreme stupidity.",
 	"You can create your own opportunities this week.  Blackmail a senior executive.",
 	"You can do very well in speculation where land or anything to do with dirt is concerned.",
 	"You can rent this space for only $5 a week.",
-	"You could live a better life, if you had a better mind and a better body.",
 	"You definitely intend to start living sometime soon.",
-	"You dialed 5483.",
 	"You display the wonderful traits of charm and courtesy.",
 	"You don't become a failure until you're satisfied with being one.",
 	"You enjoy the company of other people.",
 	"You feel a whole lot more like you do now than you did when you used to.",
 	"You fill a much-needed gap.",
 	"You get along very well with everyone except animals and people.",
-	"You had some happiness once, but your parents moved away, and you had to leave it behind.",
 	"You have a deep appreciation of the arts and music.",
 	"You have a deep interest in all that is artistic.",
 	"You have a reputation for being thoroughly reliable and trustworthy. A pity that it's totally undeserved.",
-	"You have a strong appeal for members of the opposite sex.",
-	"You have a strong appeal for members of your own sex.",
-	"You have a strong desire for a home and your family interests come first.",
 	"You have a truly strong individuality.",
 	"You have a will that can be influenced by all with whom you come in contact.",
 	"You have an ability to sense and know higher truth.",
@@ -284,7 +255,6 @@ export const fortunes = [
 	"You have an unusual magnetic personality. Don't walk too close to metal objects which are not fastened down.",
 	"You have an unusual understanding of the problems of human relationships.",
 	"You have been selected for a secret mission.",
-	"You have Egyptian flu: you're going to be a mummy.",
 	"You have had a long-term stimulation relative to business.",
 	"You have literary talent that you should take pains to develop.",
 	"You have many friends and very few living enemies.",
@@ -304,14 +274,11 @@ export const fortunes = [
 	"You may get an opportunity for advancement today.  Watch it!",
 	"You may worry about your hair-do today, but tomorrow much peanut butter will be sold.",
 	"You need more time; and you probably always will.",
-	"You need no longer worry about the future.  This time tomorrow you'll be dead.",
 	"You never hesitate to tackle the most difficult problems.",
 	"You never know how many friends you have until you rent a house on the beach.",
-	"You now have Asian Flu.",
 	"You own a dog, but you can only feed a cat.",
 	"You plan things that you do not even attempt because of your extreme caution.",
 	"You possess a mind not merely twisted, but actually sprained.",
-	"You prefer the company of the opposite sex, but are well liked by your own.",
 	"You recoil from the crude; you tend naturally toward the exquisite.",
 	"You seek to shield those you love and you like the role of the provider.",
 	"You shall be rewarded for a dastardly deed.",
@@ -320,7 +287,6 @@ export const fortunes = [
 	"You single-handedly fought your way into this hopeless mess.",
 	"You teach best what you most need to learn.",
 	"You too can wear a nose mitten.",
-	"You two ought to be more careful--your love could drag on for years and years.",
 	"You will always get the greatest recognition for the job you least like.",
 	"You will always have good luck in your personal affairs.",
 	"You will attract cultured and artistic people to your home.",
@@ -328,65 +294,42 @@ export const fortunes = [
 	"You will be advanced socially, without any special effort on your part.",
 	"You will be aided greatly by a person whom you thought to be unimportant.",
 	"You will be attacked by a beast who has the body of a wolf, the tail of a lion, and the face of Donald Duck.",
-	"You will be audited by the Internal Revenue Service.",
-	"You will be awarded a medal for disregarding safety in saving someone.",
 	"You will be awarded some great honor.",
 	"You will be awarded the Nobel Peace Prize... posthumously.",
 	"You will be called upon to help a friend in trouble.",
-	"You will be divorced within a year.",
 	"You will be given a post of trust and responsibility.",
-	"You will be held hostage by a radical group.",
 	"You will be honored for contributing your time and skill to a worthy cause.",
 	"You will be imprisoned for contributing your time and skill to a bank robbery.",
-	"You will be married within a year, and divorced within two.",
-	"You will be married within a year.",
 	"You will be misunderstood by everyone.",
 	"You will be recognized and honored as a community leader.",
 	"You will be reincarnated as a toad; and you will be much happier.",
 	"You will be run over by a beer truck.",
 	"You will be run over by a bus.",
 	"You will be singled out for promotion in your work.",
-	"You will be successful in love.",
 	"You will be surprised by a loud noise.",
 	"You will be surrounded by luxury.",
 	"You will be the last person to buy a Chrysler.",
 	"You will be the victim of a bizarre joke.",
-	"You will be Told about it Tomorrow.  Go Home and Prepare Thyself.",
 	"You will be traveling and coming into a fortune.",
 	"You will be winged by an anti-aircraft battery.",
 	"You will become rich and famous unless you don't.",
-	"You will contract a rare disease.",
 	"You will engage in a profitable business activity.",
 	"You will experience a strong urge to do good; but it will pass.",
-	"You will feel hungry again in another hour.",
 	"You will forget that you ever knew me.",
-	"You will gain money by a fattening action.",
-	"You will gain money by a speculation or lottery.",
-	"You will gain money by an illegal action.",
-	"You will gain money by an immoral action.",
 	"You will get what you deserve.",
 	"You will give someone a piece of your mind, which you can ill afford.",
-	"You will have a long and boring life.",
 	"You will have a long and unpleasant discussion with your supervisor.",
 	"You will have domestic happiness and faithful friends.",
 	"You will have good luck and overcome many hardships.",
 	"You will have long and healthy life.",
 	"You will hear good news from one you thought unfriendly to you.",
-	"You will inherit millions of dollars.",
 	"You will inherit some money or a small piece of land.",
-	"You will live a long, healthy, happy life and make bags of money.",
-	"You will live to see your grandchildren.",
 	"You will lose your present job and have to become a door to door mayonnaise salesman.",
 	"You will meet an important person who will help you advance professionally.",
-	"You will never know hunger.",
 	"You will not be elected to public office this year.",
-	"You will obey or molten silver will be poured into your ears.",
-	"You will outgrow your usefulness.",
 	"You will overcome the attacks of jealous associates.",
-	"You will pass away very quickly.",
 	"You will pay for your sins.  If you have already paid, please disregard this message.",
 	"You will pioneer the first Martian colony.",
-	"You will probably marry after a very brief courtship.",
 	"You will reach the highest possible point in your business or profession.",
 	"You will receive a legacy which will place you above want.",
 	"You will remember something that you should not have forgotten.",
@@ -395,7 +338,6 @@ export const fortunes = [
 	"You will step on the night soil of many countries.",
 	"You will stop at nothing to reach your objective, but only because your brakes are defective.",
 	"You will triumph over your enemy.",
-	"You will visit the Dung Pits of Glive soon.",
 	"You will win success in whatever calling you adopt.",
 	"You will wish you hadn't.",
 	"You work very hard.  Don't try to think as well.",
@@ -404,40 +346,26 @@ export const fortunes = [
 	"You'd like to do it instantaneously, but that's too slow.",
 	"You'll be called to a post requiring ability in handling groups of people.",
 	"You'll be sorry...",
-	"You'll feel devilish tonight.  Toss dynamite caps under a flamenco dancer's heel.",
 	"You'll feel much better once you've given up hope.",
-	"You'll never be the man your mother was!",
 	"You'll never see all the places, or read all the books, but fortunately, they're not all recommended.",
 	"You'll wish that you had done some of the hard things when they were easier to do.",
 	"You're a card which will have to be dealt with.",
 	"You're almost as happy as you think you are.",
 	"You're at the end of the road again.",
-	"You're being followed.  Cut out the hanky-panky for a few days.",
 	"You're currently going through a difficult transition period called \"Life.\"",
 	"You're definitely on their list.  The question to ask next is what list it is.",
 	"You're growing out of some of your problems, but there are others that you're growing into.",
-	"You're not my type.  For that matter, you're not even my species!",
-	"You're ugly and your mother dresses you funny.",
 	"You're working under a slight handicap.  You happen to be human.",
 	"You've been leading a dog's life.  Stay off the furniture.",
 	"Your aim is high and to the right.",
 	"Your aims are high, and you are capable of much.",
 	"Your analyst has you mixed up with another patient.  Don't believe a thing he tells you.",
 	"Your best consolation is the hope that the things you failed to get weren't really worth having.",
-	"Your boss climbed the corporate ladder, wrong by wrong.",
-	"Your boss is a few sandwiches short of a picnic.",
-	"Your boyfriend takes chocolate from strangers.",
-	"Your business will assume vast proportions.",
-	"Your business will go through a period of considerable expansion.",
 	"Your depth of comprehension may tend to make you lax in worldly ways.",
-	"Your domestic life may be harmonious.",
 	"Your fly might be open (but don't check it just now).",
 	"Your heart is pure, and your mind clear, and your soul devout.",
 	"Your ignorance cramps my conversation.",
 	"Your life would be very empty if you had nothing to regret.",
-	"Your love life will be happy and harmonious.",
-	"Your love life will be... interesting.",
-	"Your lover will never wish to leave you.",
 	"Your lucky color has faded.",
 	"Your lucky number has been disconnected.",
 	"Your lucky number is 3552664958674928.  Watch for it everywhere.",
@@ -450,7 +378,6 @@ export const fortunes = [
 	"Your present plans will be successful.",
 	"Your reasoning is excellent -- it's only your basic assumptions that are wrong.",
 	"Your reasoning powers are good, and you are a fairly good planner.",
-	"Your sister swims out to meet troop ships.",
 	"Your society will be sought by people of taste and refinement.",
 	"Your step will soil many countries.",
 	"Your supervisor is thinking about you.",