File Viewer Supported File Types: What Images, Audio, PDFs, and DOCX Files Can Pi Web Preview?

Pi Web's File Viewer can preview images (PNG, JPG, GIF, WEBP, SVG, and more), audio files (MP3, WAV, OGG, FLAC, and others), plus PDF and DOCX documents — using specialized viewer components selected by helper functions in lib/file-types.ts.

The Pi Web file viewer is a React-based component that dynamically selects the appropriate preview renderer based on file extension. According to the agegr/pi-web source code, three core helper functions determine which viewer component to mount, enabling zero-config preview support for media and document formats.

Image File Support in File Viewer

Images are detected by the isImagePath() helper defined in lib/file-types.ts. This function checks file extensions against a whitelist of web-compatible image formats.

Supported image extensions:

• png, jpg, jpeg
• gif, webp, svg
• bmp, ico, avif

When isImagePath(filePath) returns true, components/FileViewer.tsx renders the <ImageViewer> component:

// components/FileViewer.tsx (lines 35-44)
if (isImagePath(filePath)) {
  return <ImageViewer … />;
}

The ImageViewer component displays images via a standard <img> tag and supports live-sync updates for files that change during viewing.

Audio File Support in File Viewer

Audio files trigger the <AudioViewer> component, which renders a native HTML5 <audio> element with full playback controls.

Supported audio extensions:

• mp3, wav, ogg, oga
• opus, m4a, aac
• flac, weba, webm

The selection logic in components/FileViewer.tsx checks isAudioPath():

if (isAudioPath(filePath)) {
  return <AudioViewer … />;
}

The AudioViewer provides standard browser audio controls without requiring external players or plugins.

PDF and DOCX Document Preview Support

Document previews are handled by a single component that branches based on file type. The isDocumentPreviewPath() helper identifies both PDF and DOCX files.

Supported document extensions:

• pdf
• docx

From components/FileViewer.tsx:

if (isDocumentPreviewPath(filePath)) {
  return <DocumentViewer … />;
}

The DocumentViewer implementation differs by format:

• PDF files stream directly via <iframe> embedding
• DOCX files require server-generated HTML preview and are subject to a 10 MiB size limit

File Size Limits and Fallback Behavior

The lib/file-types.ts module exports size constants that constrain preview generation:

Constant	Default Value	Applies To
IMAGE_PREVIEW_MAX_BYTES	Configurable limit	All image formats
DOCX_PREVIEW_MAX_BYTES	10,485,760 bytes (10 MiB)	DOCX files only

When a file exceeds its preview limit, the File Viewer automatically falls back to a download link instead of attempting to render the preview.

Programmatic File Type Detection

For custom integrations or plugins, reuse the same helper functions exported from lib/file-types.ts:

import { isImagePath, isAudioPath, isDocumentPreviewPath } from '@/lib/file-types';

function FilePreview({ filePath }: { filePath: string }) {
  if (isImagePath(filePath)) {
    return <img src={`/api/files/${filePath}`} alt={filePath} />;
  }
  if (isAudioPath(filePath)) {
    return <audio src={`/api/files/${filePath}`} controls />;
  }
  if (isDocumentPreviewPath(filePath)) {
    return <iframe src={`/api/files/${filePath}`} title={filePath} />;
  }
  // Fallback: show raw text or download link
  return <a href={`/api/files/${filePath}`}>Download {filePath}</a>;
}

To check extension support directly, use the getFileExt() utility:

import { getFileExt } from '@/lib/file-types';

const supported = ['png', 'mp3', 'pdf', 'docx'];
function canPreview(filePath: string): boolean {
  return supported.includes(getFileExt(filePath));
}

Key Source Files

File	Responsibility
components/FileViewer.tsx	Routes files to correct viewer component based on is*Path() helpers
lib/file-types.ts	Defines extension maps, helper functions, and size limits
components/ImageViewer.tsx	Renders image files with live-update support
components/AudioViewer.tsx	Renders native audio player with controls
components/DocumentViewer.tsx	Renders PDF via iframe; DOCX via server HTML preview

Summary

• Image previews cover 9 formats including modern standards like AVIF and legacy formats like BMP
• Audio previews support 10 formats with native browser playback
• Document previews handle PDF streaming and DOCX HTML conversion with file size enforcement
• All detection logic is centralized in lib/file-types.ts for consistent behavior across the application
• Size limits prevent memory issues on large files, automatically degrading to download links

Frequently Asked Questions

Does Pi Web File Viewer support video files?

No, the current implementation does not include a video preview component. The isAudioPath() helper in lib/file-types.ts captures webm audio but not video streams. Video files fall through to the default download behavior.

Can I extend File Viewer to support additional file types?

Yes, extend the helper functions in lib/file-types.ts with new extension arrays, then add corresponding viewer components in components/FileViewer.tsx. The modular structure separates type detection from rendering logic.

Why does DOCX preview have a 10 MiB limit while PDF does not?

DOCX files require server-side HTML generation, which consumes significant memory and processing resources. The DOCX_PREVIEW_MAX_BYTES constant prevents server overload. PDFs stream directly to the browser iframe without server transformation, so they bypass this limit.

How does File Viewer handle unknown or unsupported file types?

Files that fail all is*Path() checks render as a plain download link with the filename. No preview component mounts, and the user receives a direct download option instead.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}