# Traveling Wave Phase: Turning Position and Time Into One Angle

> Phase is never time and never position on its own, it's whatever a position and an elapsed-time offset sum into before the result is handed to sin, the one angle sin actually consumes.

**Date:** 2026-10-18T00:00:00.000Z
**Tags:** Canvas, Animation, Math

## What "phase" actually means

Picture a clock hand sweeping slowly around a blank dial, no numbers on
it, nothing else moving, starting from wherever it happens to be
pointing first. At any instant you can ask "where's it pointing?", and
the honest answer is a single number: how far around the full circle the
hand has swept since it started.

No sweep yet is wherever it started, a quarter turn is "a quarter of the
way around," and all the way back to where it started is "one full
loop," then it starts counting again from zero.

That one number, *how far around one full loop something has gone*, is
all **phase** ever means. It has nothing to do with clocks specifically,
and nothing to do with circles you can literally see, anything that
repeats (a wave rising and falling, a dial sweeping around, a sound
vibrating) has a phase: the same "how far into this one repeat am I"
number, just attached to a different kind of motion.

A dot bobbing up and down on a wave is doing the exact same sweep as
that clock hand, just redrawn as a height instead of a direction. "A
quarter of the way through one up-and-down cycle" is the same kind of
fact whether it's a hand pointing east or a dot sitting at the peak of a
wave, phase is the number that fact gets written down as.

Code and math don't write that number as "a quarter turn" or "90
degrees," they write it in
radians (The unit sin/cos actually take as input. One full loop is 2π radians, the same way one full loop is 360 degrees, just a different-sized unit for the same single turn.),
a different-sized ruler for the same idea: one full loop is `2π`
radians instead of `360°`. `sin(phase)`
and `cos(phase)` are the two functions whose entire job is reading that
"how far around" number and turning it into an actual position, nothing
more than that.

## The intuition

`((x + shift) / waveLength) * 2 * Math.PI` looks like an arbitrary pile
of operations bolted together, an add, a divide, a multiply, in no order
that explains itself. It isn't arbitrary. Every piece has one specific
job, and together they're a named, standard formula, not a one-off
massaging of numbers until the animation looked right.

This formula is what makes a point move up and down to trace the wave's
shape, over and over, forever. The job is to take something that keeps
climbing, with no ceiling, and turn it into a height that keeps
oscillating (Swinging back and forth between two extremes, over and over, instead of settling anywhere. A dot bobbing between a wave's top and bottom is oscillating; a value that climbs and never comes back down isn't.)
between a top and a bottom, in step with the wave.

That climbing value isn't hypothetical, it's a real line from the wavy
loading indicator this post's formula is pulled from: `shiftAnimatable.value`.
It's an animation that counts up from `0` to `waveLength`, wraps back to
`0`, and counts up again, on a loop that never stops. On its own it's
just a number getting steadily bigger, it has no idea "up" and "down"
even exist. This formula is what turns that one climbing number into the
dot's actual height, over and over, in sync with the wave:

```kotlin
val startPhase = (shiftAnimatable.value / waveLength) * 2 * Math.PI
val startY = center.y - amplitude * sin(startPhase)
```

Two pieces, each one doing a specific job in turning "an ever-climbing
animation value" into "phase":

* **`startPhase` is phase itself**, the exact "how far around one full
  loop" number from the clock-hand analogy above, just measured for this
  wave's cycle instead of a hand sweeping around a dial. Once you know `startPhase`,
  `sin(startPhase)` tells you exactly how high the dot sits, the same
  way once you know the hand's angle, you know exactly where it's
  pointing. Nothing about `startPhase` is a position in pixels or a
  moment in time by itself, it's purely "how far around."
* **`2 * PI` is the unit conversion**, clock-style degrees traded for
  radians. `shiftAnimatable.value / waveLength` is "what fraction of one
  full wave repeat has this animation covered," the exact same question
  as "what fraction of the dial has the hand swept." Multiplying that
  fraction by `2π` turns it into the actual angle `sin` expects, because
  `sin` always completes one loop every `2π`, the same fixed way a clock
  face always completes one loop every `360°`, not something either
  formula gets to choose.

That's the whole formula for one specific point on the wave, the one
that never drifts sideways. Most points on a wave do drift sideways too,
which folds a second ingredient into this same sum, covered in "More
cases" below.

* [Polar to Cartesian: What cos and sin Are Actually Computing](/polar-to-cartesian-point) — The same '2π per cycle' idea, but spent on an angle around a circle instead of a distance along a line.

* [animate\*AsState vs Animatable: Animation Is Just an Interpolated Value](/compose-value-based-animation) — What shiftAnimatable.value and infiniteRepeatable are actually doing on every frame, underneath this post's formula.

* [Screen Coordinate Systems Aren't Cartesian: Y Points Down, Not Up](/screen-coordinate-system) — Why this post's formula subtracts amplitude \* sin(phase) from center.y instead of adding it.

## Concrete example

This is the real calculation behind a wavy loading indicator, trimmed to
just the phase math. It takes a position `x` too, the second ingredient
mentioned above, held at `0` below to match the single-point formula
from "The intuition":

```kotlin
val waveLength = 46f // px, one full wave repeat
val amplitude = 6f   // px

fun heightAt(x: Float, shift: Float): Float {
    val phase = ((x + shift) / waveLength) * 2 * Math.PI
    return (center.y - amplitude * sin(phase)).toFloat()
}
```

Walk `shift` through one full `waveLength` while `x` stays at `0`, the
exact situation the wave's fixed start dot is in:

```kotlin
heightAt(x = 0f, shift = 0f)     // phase = 0        → sin = 0     → center.y
heightAt(x = 0f, shift = 11.5f)  // phase = π/2       → sin = 1     → center.y - amplitude (top)
heightAt(x = 0f, shift = 23f)    // phase = π         → sin = 0     → center.y
heightAt(x = 0f, shift = 34.5f)  // phase = 3π/2      → sin = -1    → center.y + amplitude (bottom)
heightAt(x = 0f, shift = 46f)    // phase = 2π        → sin = 0     → center.y, back to the start
```

`shift` traveling one full `waveLength` (`46` px) makes `phase` travel
exactly one full `2π`, which is exactly one full `sin` cycle, top,
middle, bottom, middle. That's not a coincidence, it's the `2π`
conversion doing its one job: make "one `waveLength` of distance" equal
"one lap of `sin`." `shiftAnimatable` then does exactly this, animating
from `0` to `waveLength` on an infinite loop, which is why the dot keeps
bobbing through this same top-middle-bottom-middle sequence forever.

Drag the sliders below and watch both pictures move together: the dot's
height on the wave and the point traced on the circle both come from
the same `phase`, just read two different ways.

*\[Interactive demo: WavePhaseDemo — view this post in a browser for the live version.]*

## More cases: a point that also drifts sideways

The formula from "The intuition" is the real one, but only for the
point that never moves sideways. Here's the actual line, position and
all, next to that same point pinned at `0`:

```kotlin
val startX = 0f                     // never moves
val startPhase = ((startX + shiftAnimatable.value) / waveLength) * 2 * Math.PI

val tipX = size.width * progress()  // a second point, moves as progress animates
val tipPhase = ((tipX + shiftAnimatable.value) / waveLength) * 2 * Math.PI
```

* **Two different things get summed into that one number before it
  becomes an angle**: a position (`startX` or `tipX`) and
  `shiftAnimatable.value` (how far an independent, endlessly-looping
  `infiniteRepeatable` (An animation spec that repeats forever, cycling its value from initialValue to targetValue on a loop.)
  animation has run, closer to elapsed time). They're added together
  *before* either one becomes part of the angle, so by the time `sin`
  runs, it's looking at one combined number with no way to tell which
  part came from position and which came from time.
* **The point pinned at `startX = 0f`** gets a phase contribution from
  only `shiftAnimatable.value`, its own term in the sum is permanently
  zero, exactly the simplified formula "The intuition" opened with.
  That's why it still bobs even though it never drifts sideways:
  nothing about its `x` ever changes, and the dot bobs anyway, 100%
  from `shiftAnimatable.value` climbing.
* **The point at `tipX`** gets phase contributions from *both* terms:
  its x-position changes as `progress` climbs, on top of the exact same
  `shiftAnimatable.value` climbing underneath it. Same mechanism, now
  with two moving inputs instead of one.

Same function, same formula, and the only thing that changes between the
two points is which argument is a live value and which one is a
constant.

> **The fundamental**
>
> This is a **traveling wave's phase formula**, the same shape physics
> writes as `φ(x, t) = k(x + vt)`, where `k = 2π / wavelength` is the
> *wavenumber*, the fixed conversion factor from distance to radians.
> Position and elapsed time are two independent inputs that get summed
> into one number, the phase, before any oscillating function (`sin`,
> `cos`, or anything periodic) ever runs on it. The function doing the
> oscillating has no way to separate the two contributions back out, and
> doesn't need to, it only ever consumes the sum.

## Elsewhere: same fundamental, different framework

* **Fragment shaders (GLSL)**: a water or flag ripple effect is almost
  always `sin(uv.x * frequency + time * speed)`, `uv.x` is the position
  term, `time * speed` is the elapsed-time term, added together before
  `sin`, exactly this post's formula with `frequency` standing in for
  `2π / waveLength`.
* **Audio synthesis**: a digital oscillator computes
  `sin(2 * PI * frequency * sampleIndex / sampleRate + phaseOffset)` for
  every sample, `sampleIndex / sampleRate` is elapsed time in seconds,
  `frequency` plays the same role `1 / waveLength` plays here, and
  `phaseOffset` is a pure phase-shift term with no time or position
  attached to it at all.
* **Physics, the original source**: the traveling wave equation
  `y(x, t) = A·sin(kx - ωt)` is the same formula this post has been
  using the whole time, `k = 2π/λ` (the wavenumber) plays the role
  `2π / waveLength` plays here, `x` is position, `t` is time. The
  canonical form subtracts the time term; this post's code adds it
  instead, same idea, opposite sign, which is exactly the
  direction-of-travel edge case below.

## Edge cases

**Dropping the `2π`, or using the wrong constant.** `sin(distance /
waveLength)` still compiles and still oscillates, it just completes a
full cycle every `2π * waveLength` pixels instead of every `waveLength`
pixels. Nothing crashes; the wave just silently stops matching the
`waveLength` constant the rest of the code assumes.

**Flipping the sign between the position and time terms.** `x + shift`
and `x - shift` both oscillate identically at any single frozen instant,
the difference only shows up over time: `+shift` makes the wave pattern
appear to slide one direction as `shift` climbs, `-shift` slides it the
other way. Picking the wrong sign doesn't break the shape, it reverses
the direction of travel, a bug that's invisible in a screenshot and only
shows up once you actually watch it animate.

**Confusing `waveLength` with the animation's duration.** `waveLength` is
a *distance* (pixels per repeat); `durationMillis` on the
`shiftAnimatable` animation is a *duration* (milliseconds per repeat).
Changing `WaveSpeed` in the real code only changes `durationMillis`, so
the wave scrolls faster or slower, but `waveLength` stays fixed, so the
wave's actual shape on screen (how tall, how tightly packed) never
changes. Speed and shape are controlled by two unrelated constants that
happen to both feed the same `phase` formula.

## When to reach for it

Any time something needs to look like it's riding a repeating pattern
that is itself moving:

* **Scrolling wave/ripple effects**, a loading indicator, a water
  shader, an audio waveform visualizer, anywhere a shape needs to
  oscillate in space *and* scroll over time at the same time.
* **Multiple markers riding the same wave**, once one point's height is
  `heightAt(x, shift)`, placing N more markers is just calling the same
  function with N different `x` values, exactly like the tip/start dot
  pair above.
* **Anything with an independent "spatial frequency" and "temporal
  speed"** that need to be tunable separately, `waveLength` and
  `durationMillis` here, because they're genuinely two different
  constants, not two names for the same thing.

The signal that this is the wrong fundamental to reach for: if there's
only one input (just time, or just position, never both added together),
there's no "traveling" in traveling wave, a plain `animateFloat` driving
`sin` directly already covers it.

**Phase is never time and never position on its own, it's whatever gets
summed together before the result is handed to `sin`, and `2π` is simply
the unit that sum has to land in because that's the only unit `sin`
understands a full cycle in.**


---

Canonical page: https://recomposed.blog/traveling-wave-phase