# FPL — FREQUENCY PROGRAMMING LANGUAGE
## Complete Beginner's Training Guide
### Version 2.0 | Sirius Star Lab

---

## WHAT IS FPL?

FPL is a programming language where **sound frequencies are the source code**.

Instead of typing `if` or `loop` in English, you use a frequency. Each frequency IS a command — not a letter that spells a command, but the command itself. Play 192Hz and the interpreter executes IF. Play 160Hz and it executes LOOP.

Every command also has a Sanskrit symbol — the visual form of that instruction. So every command exists in three forms simultaneously:
- **Sonic** — a frequency (e.g. 528Hz)
- **Visual** — a Sanskrit symbol (e.g. ह)
- **Logical** — an instruction (e.g. TRUE)

---

## THE GOLDEN RULE

Every FPL program must start with **BEGIN** and end with **END**.

```
BEGIN
  [your program here]
END
```

That's it. Everything else goes between those two commands.

---

## LESSON 1 — YOUR FIRST PROGRAM

The simplest FPL program outputs a value.

```
BEGIN
SET x 10
OUTPUT x
END
```

**What this does:**
1. `BEGIN` — starts the program
2. `SET x 10` — creates a variable called x and gives it the value 10
3. `OUTPUT x` — prints the value of x
4. `END` — closes the program

**Type this into the Program Editor and hit Run.** You'll see:
- The frequency sequence fire simultaneously
- The Sanskrit symbols appear
- The audio plays the command frequencies in order
- The execution log shows: x = 10, output: 10

---

## LESSON 2 — DOING MATHS

FPL has four maths commands: ADD, SUB, MUL, DIV

The syntax is always: **COMMAND [value1] [value2] [result variable]**

```
BEGIN
SET x 10
SET y 5
ADD x y total
OUTPUT total
END
```

**Result:** total = 15, output: 15

```
BEGIN
SET price 100
SET discount 20
SUB price discount final
OUTPUT final
END
```

**Result:** final = 80, output: 80

```
BEGIN
SET width 8
SET height 6
MUL width height area
OUTPUT area
END
```

**Result:** area = 48, output: 48

---

## LESSON 3 — MAKING DECISIONS (IF)

IF checks a condition. If true, it runs the block. If false, it skips to ELSE or ENDIF.

```
BEGIN
SET score 85
IF GREATER score 50
  OUTPUT score
ELSE
  OUTPUT 0
ENDIF
END
```

**What this does:** If score is greater than 50, output the score. Otherwise output 0.

**Comparison commands:**
- `EQUALS a b` — are a and b the same?
- `GREATER a b` — is a bigger than b?
- `LESS a b` — is a smaller than b?
- `NOT EQUALS a b` — are they different?

```
BEGIN
SET temperature 100
IF EQUALS temperature 100
  OUTPUT temperature
ENDIF
END
```

---

## LESSON 4 — LOOPS

LOOP repeats a block a set number of times.

```
BEGIN
SET counter 1
LOOP 5
  OUTPUT counter
  ADD counter 1 counter
ENDLOOP
END
```

**What this does:** Outputs 1, 2, 3, 4, 5 — counting up by 1 each time.

---

## LESSON 5 — FUNCTIONS

A function is a named block of code you can call whenever you need it.

```
BEGIN
DEFINE greet
  OUTPUT hello
ENDDEFINE

CALL greet
CALL greet
CALL greet
END
```

**What this does:** Defines a function called greet, then calls it three times. Output: hello hello hello.

---

## LESSON 6 — STORING AND RECALLING (PERSISTENT MEMORY)

STORE saves a value permanently — it survives after the program ends.
RECALL brings it back.

```
BEGIN
SET name Garry
STORE name x
END
```

Later, in a new program:

```
BEGIN
RECALL name result
OUTPUT result
END
```

**Result:** Garry — retrieved from persistent memory.

---

## LESSON 7 — AUDIO COMMANDS

FPL has three audio commands unique to this language.

**PLAY** — plays a frequency as sound
```
BEGIN
PLAY 432
PLAY 528
PLAY 396
END
```

**EMIT** — emits a sequence of frequencies as a program signal — transmitting the program as sound
```
BEGIN
SET x 10
EMIT 432 528 396
END
```

**LISTEN** — listens for incoming audio and decodes the frequency into a variable
```
BEGIN
LISTEN detected
OUTPUT detected
END
```

This is what makes FPL unique — you can **transmit a program as audio** and another device running FPL can **receive and execute it by listening**.

---

## LESSON 8 — DEBUGGING

If something isn't working, use DEBUG to see all current variables.

```
BEGIN
SET x 10
SET y 20
ADD x y total
DEBUG
END
```

DEBUG outputs every variable and its current value — like opening the bonnet of a car.

Use STOP to halt execution immediately if an error is detected:

```
BEGIN
SET x 0
IF EQUALS x 0
  STOP
ENDIF
OUTPUT x
END
```

---

## THE COMPLETE COMMAND REFERENCE

### FLOW CONTROL (128–256Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| BEGIN | 128Hz | ॐ | Start program |
| END | 144Hz | ऽ | End program |
| LOOP | 160Hz | ण | Begin loop |
| ENDLOOP | 176Hz | ञ | End loop |
| IF | 192Hz | ऐ | Conditional |
| ELSE | 208Hz | ऒ | Else branch |
| ENDIF | 224Hz | ऊ | End conditional |
| JUMP | 240Hz | य | Jump to label |
| LABEL | 256Hz | र | Define jump target |

### DATA (288–416Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| SET | 288Hz | क | Assign variable |
| GET | 304Hz | ख | Retrieve variable |
| COPY | 320Hz | ग | Copy variable |
| CLEAR | 336Hz | घ | Reset variable to zero |
| PUSH | 352Hz | च | Push to stack |
| POP | 368Hz | छ | Pop from stack |
| SWAP | 384Hz | ज | Swap two variables |
| TYPE | 400Hz | झ | Declare variable type |

### LOGIC (432–528Hz — Solfeggio frequencies)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| EQUALS | 432Hz | 𑀢 | Test equality |
| GREATER | 448Hz | 𑀉 | Test greater than |
| LESS | 464Hz | 𑀇 | Test less than |
| AND | 480Hz | 𑀅 | Logical AND |
| OR | 496Hz | 𑀏 | Logical OR |
| NOT | 512Hz | 𑀦 | Logical NOT |
| TRUE | 528Hz | ह | Boolean true |

### INPUT / OUTPUT (540–639Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| OUTPUT | 540Hz | व | Print a value |
| INPUT | 561Hz | स | Receive input |
| PLAY | 582Hz | ष | Play frequency as audio |
| LISTEN | 603Hz | श | Listen for frequency input |
| EMIT | 624Hz | ल | Emit frequencies as signal |
| RETURN | 639Hz | र | Return from function |

### MATHS (648–741Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| ADD | 648Hz | म | Add two values |
| SUB | 672Hz | भ | Subtract |
| MUL | 693Hz | ब | Multiply |
| DIV | 714Hz | फ | Divide |
| MOD | 741Hz | प | Modulo (remainder) |

### MEMORY (756–852Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| STORE | 756Hz | न | Save to persistent memory |
| RECALL | 777Hz | ध | Load from persistent memory |
| DEFINE | 798Hz | द | Define a function |
| ENDDEFINE | 819Hz | थ | Close function definition |
| CALL | 840Hz | त | Call a function |
| FORGET | 852Hz | ट | Delete from persistent memory |

### SYSTEM (864–963Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| WAIT | 864Hz | ण | Pause N milliseconds |
| STOP | 888Hz | ड | Stop execution |
| REPEAT | 906Hz | ढ | Repeat last command N times |
| DEBUG | 936Hz | ङ | Output all variables |
| VERSION | 963Hz | ऋ | Output FPL version info |

### SYNTAX (0–123Hz)
| Command | Frequency | Symbol | What it does |
|---|---|---|---|
| SEP | 0Hz | ∅ | Separator between commands |
| OPEN | 111Hz | ( | Open parameter group |
| CLOSE | 117Hz | ) | Close parameter group |
| CHAIN | 123Hz | → | Chain output to next command |

---

## FIVE COMPLETE EXAMPLE PROGRAMS

### Program 1 — Counter
```
BEGIN
SET i 1
LOOP 10
  OUTPUT i
  ADD i 1 i
ENDLOOP
END
```
Counts from 1 to 10.

### Program 2 — Temperature Check
```
BEGIN
SET temp 37
IF GREATER temp 38
  OUTPUT fever
ELSE
  OUTPUT normal
ENDIF
END
```

### Program 3 — Simple Calculator
```
BEGIN
SET a 25
SET b 4
ADD a b sum
SUB a b diff
MUL a b product
DIV a b quotient
OUTPUT sum
OUTPUT diff
OUTPUT product
OUTPUT quotient
END
```

### Program 4 — Store and Recall
```
BEGIN
SET username Garry
STORE username saved
FORGET username
RECALL saved username
OUTPUT username
END
```

### Program 5 — Function with Loop
```
BEGIN
DEFINE countdown
  SET n 5
  LOOP 5
    OUTPUT n
    SUB n 1 n
  ENDLOOP
ENDDEFINE

CALL countdown
END
```
Counts down from 5 to 1.

---

## HOW THE FREQUENCIES WORK

When you run a program, the system simultaneously:

1. **Parses** your text into a command sequence
2. **Maps** each command to its frequency
3. **Assigns** the Sanskrit symbol for each command
4. **Generates** a WAV audio file — the program as playable sound
5. **Executes** the logic and shows the result
6. **Compiles** the JSON representation

The audio file IS the program. If you play that audio file to another FPL interpreter using LISTEN, it will execute the same program. The sound carries the code.

---

## TIPS FOR WRITING FPL PROGRAMS

1. **Always BEGIN and END** — the interpreter will reject programs without these
2. **Variable names are single words** — `x`, `total`, `counter`, `name` — no spaces
3. **Values follow commands directly** — `SET x 10` not `SET x = 10`
4. **Maths always has three parts** — command, input1, input2, result: `ADD x y total`
5. **IF always needs ENDIF** — even if there's no ELSE
6. **LOOP always needs ENDLOOP** — open blocks must be closed
7. **Use DEBUG when stuck** — it shows you every variable at that moment

---

*FPL v2.0 — Sirius Star Lab — frequency.sirius-ai.live*