spotclip/README.md

Instagram-Style Video Widget for websites

# 🎥 SpotVid - Instagram-Style Video Widget

Transform your website with engaging, vertical-scrolling video content that captures your visitors' attention!

## ✨ Features

- 🔵 Sleek, floating video button in customizable positions
- 📱 Full-screen vertical video experience (like Instagram Reels)
- 🎯 Smooth scrolling between videos
- 🔊 Easy sound controls and intuitive interface
- 🎬 Support for MP4 and HLS video formats
- 📱 Responsive design for all devices
- 🚀 Lightweight (<50KB gzipped)
- 🔄 Video preloading for instant playback
- 🎨 Highly customizable appearance
- 📊 Built-in analytics hooks

## 🚀 Getting Started

### Basic Installation

Add the script to your HTML:

```html
<script src="https://cdn.spotvid.com/v1/spotvid.min.js"></script>
```

Initialize with configuration:

```html
<script>
window.SpotVid.init({
  videos: [{
    url: 'https://example.com/video1.mp4',
    title: 'Product 1',
    thumbnail: 'https://example.com/thumb1.jpg',
    link: 'https://example.com/product1'
  }],
  style: {
    widget_x_position: 0,  // 0 = left, 100 = right
    widget_y_position: 0,  // 0 = bottom, 100 = top
    size: '150px'
  }
});
</script>
```

### NPM Installation

```bash
npm install spotvid-widget
```

```javascript
import SpotVid from 'spotvid-widget';

new SpotVid({
  videos: [...],
  style: {...}
});
```

## 💻 Technical Requirements

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Support for ES6+ JavaScript
- Minimal impact on page load (<100ms)
- Bandwidth for video streaming

## ⚙️ Configuration Options

```javascript
{
  videos: [{
    url: string,          // Video URL (required)
    title: string,        // Video title
    thumbnail: string,    // Thumbnail image URL
    link: string,         // CTA link URL
    duration: number      // Video duration in seconds
  }],
  style: {
    widget_x_position: number,  // 0-100: 0 = left, 100 = right
    widget_y_position: number,  // 0-100: 0 = bottom, 100 = top
    size: string,         // Widget size (e.g. '150px')
    borderColor: string,  // Border color
    borderWidth: string,  // Border width
    pillBackground: string, // Notification pill background
    pillTextColor: string  // Notification pill text color
  },
  mode: string,           // 'stories' | 'reels'
  pillText: string,       // Notification text
  ctaText: string,        // Call-to-action button text
  analytics: {
    onPlay: Function,     // Play event callback
    onComplete: Function, // Complete event callback
    onCTA: Function      // CTA click callback
  }
}
```

## 📱 Mobile Experience

Optimized for mobile devices with:
- Touch-friendly controls
- Smooth vertical swiping
- Adaptive video quality
- Portrait mode optimization
- Safe area handling
- Gesture navigation

## 🎯 Events & Analytics

```javascript
SpotVid.init({
  analytics: {
    onPlay: (videoId) => {
      console.log(`Video ${videoId} started playing`);
    },
    onComplete: (videoId) => {
      console.log(`Video ${videoId} completed`);
    },
    onCTA: (videoId, url) => {
      console.log(`CTA clicked for video ${videoId}`);
    }
  }
});
```

## 🔒 Security & Performance

- HTTPS video delivery
- CDN distribution
- Efficient preloading
- Minimal bundle size
- Content security policy compliant
- Cross-origin resource sharing

## 🛠 API Methods

```javascript
const widget = new SpotVid(config);

// Control methods
widget.play();              // Play current video
widget.pause();             // Pause current video
widget.next();             // Go to next video
widget.previous();         // Go to previous video
widget.setMuted(boolean);  // Toggle sound
widget.destroy();          // Remove widget

// State methods
widget.isPlaying();        // Check if playing
widget.getCurrentVideo();  // Get current video data
widget.getConfig();       // Get current config
```

## 🎨 Styling

Custom CSS variables for styling:

```css
:root {
  --spotvid-primary: #000000;
  --spotvid-text: #FFFFFF;
  --spotvid-border-radius: 50%;
  --spotvid-shadow: 0 2px 10px rgba(0,0,0,0.2);
  --spotvid-z-index: 999;
}
```

## 🛠 Support

Need help? We've got you covered:
- 📧 Email: support@spotvid.com
- 💬 Discord: [Join our community](https://discord.gg/spotvid)
- 📚 Documentation: [docs.spotvid.com](https://docs.spotvid.com)
- 🐛 Issues: [GitHub Issues](https://github.com/axioms-studio/spotvid/issues)

## 🗺️ Roadmap

Coming soon:
- 📊 Enhanced analytics
- 🌐 Social sharing
- 🎯 A/B testing
- 📺 Live streaming
- 🔄 Auto-play options
- 🎨 More themes

## 📄 License

MIT License - Copyright (c) 2024 Axioms Studio

---

Made with ❤️ by [Axioms Studio](https://axioms.studio)