# mewkiz/flac architecture

> Architecture diagram of the GitHub repository mewkiz/flac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mewkiz/flac
- Repository: https://github.com/mewkiz/flac

## Overview

This is a Go library for reading and writing FLAC audio streams. A caller opens a reader or seeker as a Stream, which parses stream metadata, advances through audio frames, and decodes their channel subframes into samples; seeking uses the seek table and frame positions. The experimental encoder writes metadata and audio frames, with separate subframe encoding. Metadata block types and low-level bit and checksum helpers support these paths. Some encoder wiring and seeking details are documented or indexed but not shown in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`frame/frame.go`](https://github.com/mewkiz/flac/blob/master/frame/frame.go) (Frame parser), [`encode.go`](https://github.com/mewkiz/flac/blob/master/encode.go) (Encoder API), [`encode_frame.go`](https://github.com/mewkiz/flac/blob/master/encode_frame.go) (Frame encoder), [`flac.go`](https://github.com/mewkiz/flac/blob/master/flac.go) (Stream API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stream["Stream access"]
  node_stream_api["Stream API<br/>[flac.go]"]
  node_seek["Frame seeking<br/>[flac.go]"]
end

subgraph group_metadata["Metadata"]
  node_metadata_reader["Block reader<br/>[meta.go]"]
  node_metadata_types["Metadata types"]
end

subgraph group_audio["Audio frames"]
  node_frame_parser["Frame parser<br/>[frame.go]"]
  node_subframe_decoder["Subframe decoder<br/>[subframe.go]"]
end

subgraph group_encoding["Encoding"]
  node_encoder_api["Encoder API<br/>[encode.go]"]
  node_frame_encoder["Frame encoder<br/>[encode_frame.go]"]
  node_subframe_encoder["Subframe encoder<br/>[encode_subframe.go]"]
  node_metadata_encoder["Metadata encoder<br/>[encode_meta.go]"]
end

subgraph group_internals["Format primitives"]
  node_bit_reader["Bit reader<br/>[reader.go]"]
  node_checksum["Frame checksums"]
  node_number_codec["Frame number codec"]
  node_seek_buffer["Buffered seeker<br/>[readseeker.go]"]
end

node_caller(("Library caller"))
node_audio_output["Decoded samples"]
node_flac_output["FLAC stream"]

node_caller -->|"opens stream"| node_stream_api
node_stream_api -->|"parses blocks"| node_metadata_reader
node_metadata_reader -->|"dispatches types"| node_metadata_types
node_stream_api -.->|"parses frames"| node_frame_parser
node_frame_parser -->|"parses subframes"| node_subframe_decoder
node_subframe_decoder -->|"reads bits"| node_bit_reader
node_frame_parser -->|"reads headers"| node_bit_reader
node_frame_parser -->|"checks frames"| node_checksum
node_frame_parser -.->|"decodes numbers"| node_number_codec
node_subframe_decoder -->|"decodes samples"| node_audio_output
node_caller -->|"seeks samples"| node_seek
node_seek -->|"buffers seeks"| node_seek_buffer
node_seek -->|"parses frames"| node_frame_parser
node_caller -.->|"encodes audio"| node_encoder_api
node_encoder_api -.->|"writes metadata"| node_metadata_encoder
node_encoder_api -.->|"writes frames"| node_frame_encoder
node_frame_encoder -.->|"encodes subframes"| node_subframe_encoder
node_frame_encoder -->|"checks frame data"| node_checksum
node_frame_encoder -.->|"encodes numbers"| node_number_codec
node_metadata_encoder -->|"serializes types"| node_metadata_types
node_encoder_api -.->|"writes stream"| node_flac_output

click node_stream_api "https://github.com/mewkiz/flac/blob/master/flac.go"
click node_seek "https://github.com/mewkiz/flac/blob/master/flac.go"
click node_metadata_reader "https://github.com/mewkiz/flac/blob/master/meta/meta.go"
click node_metadata_types "https://github.com/mewkiz/flac/tree/master/meta"
click node_frame_parser "https://github.com/mewkiz/flac/blob/master/frame/frame.go"
click node_subframe_decoder "https://github.com/mewkiz/flac/blob/master/frame/subframe.go"
click node_encoder_api "https://github.com/mewkiz/flac/blob/master/encode.go"
click node_frame_encoder "https://github.com/mewkiz/flac/blob/master/encode_frame.go"
click node_subframe_encoder "https://github.com/mewkiz/flac/blob/master/encode_subframe.go"
click node_metadata_encoder "https://github.com/mewkiz/flac/blob/master/encode_meta.go"
click node_bit_reader "https://github.com/mewkiz/flac/blob/master/internal/bits/reader.go"
click node_checksum "https://github.com/mewkiz/flac/tree/master/internal/hashutil"
click node_number_codec "https://github.com/mewkiz/flac/tree/master/internal/utf8"
click node_seek_buffer "https://github.com/mewkiz/flac/blob/master/internal/bufseekio/readseeker.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stream_api,node_seek toneBlue
class node_metadata_reader,node_metadata_types toneAmber
class node_frame_parser,node_subframe_decoder toneMint
class node_encoder_api,node_frame_encoder,node_subframe_encoder,node_metadata_encoder toneRose
class node_bit_reader,node_checksum,node_number_codec,node_seek_buffer,node_caller,node_audio_output,node_flac_output toneIndigo
```

## Components

### Stream access

- [Stream API](https://github.com/mewkiz/flac/blob/master/flac.go): `flac.go`
- [Frame seeking](https://github.com/mewkiz/flac/blob/master/flac.go): `flac.go`

### Metadata

- [Block reader](https://github.com/mewkiz/flac/blob/master/meta/meta.go): `meta/meta.go`
- [Metadata types](https://github.com/mewkiz/flac/tree/master/meta): `meta`

### Audio frames

- [Frame parser](https://github.com/mewkiz/flac/blob/master/frame/frame.go): `frame/frame.go`
- [Subframe decoder](https://github.com/mewkiz/flac/blob/master/frame/subframe.go): `frame/subframe.go`

### Encoding

- [Encoder API](https://github.com/mewkiz/flac/blob/master/encode.go): `encode.go`
- [Frame encoder](https://github.com/mewkiz/flac/blob/master/encode_frame.go): `encode_frame.go`
- [Subframe encoder](https://github.com/mewkiz/flac/blob/master/encode_subframe.go): `encode_subframe.go`
- [Metadata encoder](https://github.com/mewkiz/flac/blob/master/encode_meta.go): `encode_meta.go`

### Format primitives

- [Bit reader](https://github.com/mewkiz/flac/blob/master/internal/bits/reader.go): `internal/bits/reader.go`
- [Frame checksums](https://github.com/mewkiz/flac/tree/master/internal/hashutil): `internal/hashutil`
- [Frame number codec](https://github.com/mewkiz/flac/tree/master/internal/utf8): `internal/utf8`
- [Buffered seeker](https://github.com/mewkiz/flac/blob/master/internal/bufseekio/readseeker.go): `internal/bufseekio/readseeker.go`

### Other components

- **Library caller**
- **Decoded samples**
- **FLAC stream**

## Connections

- Library caller → Stream API: opens stream (evidence: `flac.go`)
- Stream API → Block reader: parses blocks (evidence: `flac.go`)
- Block reader → Metadata types: dispatches types (evidence: `meta/meta.go`)
- Stream API → Frame parser: parses frames
- Frame parser → Subframe decoder: parses subframes (evidence: `frame/frame.go`)
- Subframe decoder → Bit reader: reads bits (evidence: `frame/subframe.go`)
- Frame parser → Bit reader: reads headers (evidence: `frame/frame.go`)
- Frame parser → Frame checksums: checks frames (evidence: `frame/frame.go`)
- Frame parser → Frame number codec: decodes numbers (evidence: `frame/frame.go`)
- Subframe decoder → Decoded samples: decodes samples (evidence: `frame/subframe.go`)
- Library caller → Frame seeking: seeks samples (evidence: `flac.go`)
- Frame seeking → Buffered seeker: buffers seeks (evidence: `flac.go`)
- Frame seeking → Frame parser: parses frames (evidence: `flac.go`)
- Library caller → Encoder API: encodes audio
- Encoder API → Metadata encoder: writes metadata
- Encoder API → Frame encoder: writes frames
- Frame encoder → Subframe encoder: encodes subframes
- Frame encoder → Frame checksums: checks frame data (evidence: `encode_frame.go`)
- Frame encoder → Frame number codec: encodes numbers (evidence: `encode_frame.go`)
- Metadata encoder → Metadata types: serializes types (evidence: `encode_meta.go`)
- Encoder API → FLAC stream: writes stream
