# Vinyl Record API
> Vinyl-record geometry maths as an API, computed locally and deterministically — the playing-time, groove-length and groove-speed numbers a cutting engineer, pressing plant or audio hobbyist works a record out with. The playing-time endpoint gives a side's maximum time = the number of groove turns ÷ the turntable speed, where the turns = the recorded band's radial width ÷ the groove pitch (the spacing between adjacent grooves): a 12-inch LP with ~85 mm of band at a 100 µm pitch holds about 850 turns, so at 33⅓ rpm that is roughly 25 minutes a side — a tighter pitch fits more time but cuts groove amplitude and so loudness and bass, the classic time-versus-level trade. The groove-length endpoint unrolls the spiral: length ≈ turns × the mean circumference (π × the average of the outer and inner diameters), on the order of 400–500 metres for an LP side, the whole of which the stylus traces once. The groove-speed endpoint gives the linear speed under the stylus = 2π × rpm/60 × radius, so the outer grooves of an LP pass at about 50 cm/s but the inner ones only ~20 cm/s — the cause of inner-groove distortion and why engineers place quieter tracks last. Everything is computed locally and deterministically, so it is instant and private. Ideal for record-cutting and mastering tools, hi-fi and collector apps, and audio-engineering calculators. Pure local computation — no key, no third-party service, instant. 3 compute endpoints. For musical note and tempo maths use a music API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/vinyl-api/..."
```

## Pricing
- **Free** (Free) — 6,700 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 56,000 calls/Mo, 6 req/s
- **Pro** ($23/Mo) — 241,000 calls/Mo, 15 req/s
- **Mega** ($72/Mo) — 1,095,000 calls/Mo, 40 req/s

## Endpoints

### Vinyl

#### `GET /v1/groove-length` — Total spiral groove length

**Parameters:**
- `outer_diameter_mm` (query, required, string) — Outer recorded diameter (mm) Example: `290`
- `inner_diameter_mm` (query, required, string) — Inner recorded diameter (mm) Example: `120`
- `groove_pitch_um` (query, required, string) — Groove pitch (µm) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vinyl-api/v1/groove-length?outer_diameter_mm=290&inner_diameter_mm=120&groove_pitch_um=100"
```

**Response:**
```json
{
    "data": {
        "note": "Unrolled, the spiral groove is astonishingly long: its length ≈ the number of turns × the mean circumference (π × the average of the outer and inner diameters). A 12-inch LP side runs on the order of 400–500 metres of groove. The stylus traces this whole length once per side, which is why a tiny mistracking error repeated over half a kilometre of wall undulations is audible.",
        "inputs": {
            "groove_pitch_um": 100,
            "inner_diameter_mm": 120,
            "outer_diameter_mm": 290
        },
        "revolutions": 850,
        "groove_length_m": 547.42
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.359Z",
        "request_id": "908e7ebb-5ede-4481-9add-b1e38b0fdad4"
    },
    "status": "ok",
    "message": "Groove length",
    "success": true
}
```

#### `GET /v1/groove-speed` — Linear groove speed at a radius

**Parameters:**
- `rpm` (query, required, string) — Turntable speed (rpm) Example: `33.333`
- `radius_mm` (query, required, string) — Radius on the disc (mm) Example: `145`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vinyl-api/v1/groove-speed?rpm=33.333&radius_mm=145"
```

**Response:**
```json
{
    "data": {
        "note": "The linear speed the stylus sees = the angular speed × the radius (v = 2π × rpm/60 × r). On a constant-rpm record the outer grooves pass the stylus far faster than the inner ones — about 50 cm/s at the start of a 12-inch LP but only ~20 cm/s near the label. Less groove length per second at the inside means less room for detail, the cause of 'inner-groove distortion' and why engineers put quieter tracks last.",
        "inputs": {
            "rpm": 33.333,
            "radius_mm": 145
        },
        "linear_speed_m_per_s": 0.5061,
        "linear_speed_cm_per_s": 50.61
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.453Z",
        "request_id": "ec7a6301-e3c6-4e92-8378-97f8e0e8d80d"
    },
    "status": "ok",
    "message": "Groove speed",
    "success": true
}
```

#### `GET /v1/playing-time` — Playing time of a side

**Parameters:**
- `outer_diameter_mm` (query, required, string) — Outer recorded diameter (mm) Example: `290`
- `inner_diameter_mm` (query, required, string) — Inner recorded diameter (mm) Example: `120`
- `groove_pitch_um` (query, required, string) — Groove pitch / spacing (µm) Example: `100`
- `rpm` (query, required, string) — Turntable speed (rpm) Example: `33.333`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vinyl-api/v1/playing-time?outer_diameter_mm=290&inner_diameter_mm=120&groove_pitch_um=100&rpm=33.333"
```

**Response:**
```json
{
    "data": {
        "note": "A record's playing time = the number of groove turns ÷ the turntable speed. The turns = the recorded band's radial width ÷ the groove pitch (the spacing between adjacent grooves), so a 12-inch LP with ~85 mm of band at a 100 µm pitch holds about 850 turns, and at 33⅓ rpm that is roughly 25 minutes a side. A tighter pitch fits more time but cuts the groove amplitude — and so the loudness and bass — which is the classic time-versus-level trade a cutting engineer makes.",
        "inputs": {
            "rpm": 33.333,
            "groove_pitch_um": 100,
            "inner_diameter_mm": 120,
            "outer_diameter_mm": 290
        },
        "revolutions": 850,
        "playing_time_min": 25.5,
        "playing_time_formatted": "25:30"
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.554Z",
        "request_id": "a8571154-0550-4e70-a61a-86cc0615bcc8"
    },
    "status": "ok",
    "message": "Playing time",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vinyl-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "mm, µm, rpm. turns = (outer−inner)/2 ÷ pitch; time = turns/rpm; length = turns × π × mean diameter; speed = 2π·rpm/60·r. For musical note/tempo maths use a music API.",
        "service": "vinyl-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/groove-speed": "Linear groove speed under the stylus at a radius.",
            "GET /v1/playing-time": "Playing time and turns from the recorded band, pitch and rpm.",
            "GET /v1/groove-length": "Total spiral groove length from the band and pitch."
        },
        "description": "Vinyl-record geometry: maximum playing time, total groove length, and linear groove speed at a radius."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:49.645Z",
        "request_id": "021d9f25-3fbf-4d42-9303-50688ce25b17"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/vinyl-api
OpenAPI spec: https://www.oanor.com/api/vinyl-api/openapi.json