npm package: @stagecliplk/remotion-template
Description: Reusable Remotion Template Editor component for video template customization - includes TemplateEditor, RemotionPlayer, and supporting utilities
Author: StageClip
Latest version: 1.0.30

# @stageclip/remotion-template

[![npm version](https://img.shields.io/npm/v/@stageclip/remotion-template.svg)](https://www.npmjs.com/package/@stageclip/remotion-template)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful, reusable React component for editing and previewing Remotion video templates. Built with TypeScript and
designed for production use.

## **Features**

✅ **Rich Template Editor** - Full-featured UI for customizing video templates  
✅ **Real-time Preview** - Integrated Remotion player for instant feedback  
✅ **TypeScript Support** - Fully typed for excellent DX  
✅ **Flexible API** - Props-based, no global state  
✅ **Modular** - Import only what you need  
✅ **Production Ready** - Battle-tested in StageClip's production environment

---

## **Installation**

### **Prerequisites**

- React >= 18.0.0
- Node.js >= 18.18.0

### **Install from Azure Artifacts**

1. **Configure `.npmrc`** in your project root:

```ini
registry=https://pkgs.dev.azure.com/YOUR_ORG/_packaging/YOUR_FEED/npm/registry/
always-auth=true
```

2. **Install the package:**

```bash
npm install @stageclip/remotion-template
```

Or with yarn:

```bash
yarn add @stageclip/remotion-template
```

**Note:** Peer dependencies (`react`, `react-dom`, `remotion`, `@remotion/player`, `@remotion/media-utils`) will be
installed automatically if not present.

---

## **Quick Start**

```tsx
import React, { useState } from 'react';
import { TemplateEditor, RemotionPlayer, VideoTemplate } from '@stageclip/remotion-template';

function App() {
  const [template, setTemplate] = useState<VideoTemplate>({
    compositionDefaults: {
      fps: 30,
      width: 1920,
      height: 1080,
      aspectRatio: '16:9',
      totalFrames: 300,
    },
    globalBranding: {
      institutionName: 'My Institution',
      brandColor1: '#00802b',
      brandColor2: '#005a1e',
      brandColor3: '#00cc44',
      fontFamily: 'Inter',
      fontSize: 48,
      lineSpacing: 1.2,
      logoPrimary: '',
      logoSecondary: '',
      socialMedia: {
        websiteUrl: '',
        contactLine: '',
        instagramHandle: '',
        hashtag: '',
      },
      musicUrl: '',
      musicVolume: 0.3,
    },
    timeline: [],
  });

  return (
    <div style={{ display: 'flex', gap: 20 }}>
      <TemplateEditor
        template={template}
        selectedSceneId={null}
        onTemplateChange={setTemplate}
        onClearSelection={() => {}}
      />
      <RemotionPlayer template={template} />
    </div>
  );
}

export default App;
```

---

## **Core Components**

### **TemplateEditor**

Main component for editing video templates.

```tsx
<TemplateEditor
  template={template}
  selectedSceneId={selectedSceneId}
  onTemplateChange={handleTemplateChange}
  onClearSelection={handleClearSelection}
  onOpenMediaLibrary={handleOpenMediaLibrary}
  onAspectRatioChange={handleAspectRatioChange}
/>
```

**Props:**

- `template: VideoTemplate` - Current template configuration
- `selectedSceneId: string | null` - ID of selected scene
- `onTemplateChange: (template: VideoTemplate) => void` - Callback when template changes
- `onClearSelection: () => void` - Callback to clear selection
- `onOpenMediaLibrary?: (sceneId, propPath, mediaType, options) => void` - Optional media picker
- `onAspectRatioChange?: (aspectRatio: '16:9' | '9:16') => void` - Optional aspect ratio handler

---

### **RemotionPlayer**

Component for previewing video templates.

```tsx
<RemotionPlayer template={template} width={1280} height={720} />
```

**Props:**

- `template: VideoTemplate` - Template to preview
- `width?: number` - Player width (optional)
- `height?: number` - Player height (optional)

---

## **Exported Components**

```typescript
// Main components
import { TemplateEditor, RemotionPlayer } from '@stageclip/remotion-template';

// Sub-components
import { ColorPicker, RangeSlider, DualRangeSlider, LogoPicker, SceneTimeline } from '@stageclip/remotion-template';

// Types
import type {
  VideoTemplate,
  CompositionDefaults,
  GlobalBranding,
  SocialMedia,
  ParticipantData,
  GoogleFont,
  LogoOption,
} from '@stageclip/remotion-template';

// Utilities
import {
  GOOGLE_FONTS,
  loadGoogleFont,
  getFontFamilyString,
  calculateSceneDuration,
  colors,
  fontFamily,
} from '@stageclip/remotion-template';
```

---

## **TypeScript**

Full TypeScript support included. All types are exported:

```typescript
import type { VideoTemplate } from '@stageclip/remotion-template';

const myTemplate: VideoTemplate = {
  // Fully typed!
};
```

---

## **Documentation**

- **[Usage Guide](./USAGE.md)** - Comprehensive usage examples and patterns
- **[Publishing Guide](./PUBLISHING.md)** - How to publish updates to Azure Artifacts
- **[API Reference](./USAGE.md#api-reference)** - Complete API documentation

---

## **Examples**

### **With Media Library Integration**

```tsx
function VideoEditorWithMediaLibrary() {
  const [template, setTemplate] = useState<VideoTemplate>(initialTemplate);
  const [selectedSceneId, setSelectedSceneId] = useState<string | null>(null);

  const handleOpenMediaLibrary = (sceneId, propPath, mediaType, options) => {
    // Open your media library modal
    // Update template with selected media
  };

  return (
    <TemplateEditor
      template={template}
      selectedSceneId={selectedSceneId}
      onTemplateChange={setTemplate}
      onClearSelection={() => setSelectedSceneId(null)}
      onOpenMediaLibrary={handleOpenMediaLibrary}
    />
  );
}
```

### **With Auto-Save**

```tsx
import { useDebounce } from 'use-debounce';

function VideoEditorWithAutoSave() {
  const [template, setTemplate] = useState<VideoTemplate>(initialTemplate);
  const [debouncedTemplate] = useDebounce(template, 1000);

  useEffect(() => {
    // Auto-save to backend
    saveToBackend(debouncedTemplate);
  }, [debouncedTemplate]);

  return (
    <TemplateEditor
      template={template}
      selectedSceneId={null}
      onTemplateChange={setTemplate}
      onClearSelection={() => {}}
    />
  );
}
```

---

## **Styling**

The component uses inline styles with a built-in theme. You can wrap it in a container for additional styling:

```tsx
import { colors } from '@stageclip/remotion-template';

<div
  style={{
    backgroundColor: colors.bgPaper,
    padding: 20,
    borderRadius: 8,
  }}
>
  <TemplateEditor {...props} />
</div>;
```

**Available theme colors:**

- `colors.primary` - Primary brand color
- `colors.textPrimary` - Main text color
- `colors.bgDefault` - Default background
- `colors.bgPaper` - Paper/card background
- And more...

---

## **Browser Support**

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

---

## **Requirements**

### **Peer Dependencies**

```json
{
  "react": ">=18",
  "react-dom": ">=18",
  "remotion": ">=4",
  "@remotion/player": "^4.0.400",
  "@remotion/media-utils": "^4.0.400",
  "@remotion/transitions": "^4.0.400"
}
```

---

## **Development**

This package is developed inside the StageClip Producer monorepo.

```bash
# Navigate to package directory
cd src/shared/remotion-template

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Clean build artifacts
npm run clean
```

---

## **Publishing**

Publishing is handled through Azure Artifacts. See [PUBLISHING.md](./PUBLISHING.md) for detailed instructions.

**Quick publish:**

```bash
cd src/shared/remotion-template

# Bump version
npm version patch  # or minor, major

# Build and publish
npm publish
```

---

## **Versioning**

We follow [Semantic Versioning](https://semver.org/):

- **MAJOR** - Breaking changes
- **MINOR** - New features (backward compatible)
- **PATCH** - Bug fixes

---

## **License**

MIT © StageClip

---

## **Support**

For issues, questions, or feature requests:

- **Internal:** Contact the StageClip development team
- **External:** Create an issue in the repository

---

## **Changelog**

### **v1.0.0** (Initial Release)

- ✨ TemplateEditor component with full editing capabilities
- ✨ RemotionPlayer for video preview
- ✨ Sub-components: ColorPicker, LogoPicker, RangeSlider, etc.
- ✨ Complete TypeScript support
- ✨ Google Fonts integration
- ✨ Scene duration calculator utility
- 📚 Comprehensive documentation

---

## **Contributors**

Built and maintained by the StageClip team.