vue-streaming 0.1.4 → 2.0.0

package/README.md

@@ -1,699 +1,425 @@
-# vue-streaming
-
-<div align="center">
-**Universal Vue 3 streaming component for real-time data and media**
-
-[![npm version](https://img.shields.io/npm/v/vue-streaming.svg)](https://github.com/package/vue-streaming)
-[![Vue 3](https://img.shields.io/badge/vue-3.3%2B-brightgreen.svg)](https://vuejs.org/)
-[![TypeScript](https://img.shields.io/badge/typescript-ready-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/vue-streaming)](https://bundlephobia.com/package/vue-streaming)
-
-</div>
-
-## 🌟 Features
-
-Vue Streaming provides a unified `<StreamPlayer>` component that handles **6 different streaming protocols** with a consistent, declarative API:
-
-- 🔌 **WebSocket** - Real-time bidirectional communication
-- 📡 **Server-Sent Events (SSE)** - Server-to-client event streams
-- 🌊 **HTTP Streaming** - Chunked transfer encoding streams
-- 🔄 **Long Polling** - HTTP-based persistent connections
-- 📺 **HLS Video** - HTTP Live Streaming for adaptive video
-- 🎥 **WebRTC** - Peer-to-peer real-time communication
-
-### ✨ Why Choose Vue Streaming?
-
-- **One API, Many Protocols**: Switch between streaming types with just a prop change
-- **Vue 3 Native**: Built for Composition API with full TypeScript support
-- **Headless Design**: No imposed styling - complete UI control
-- **Production Ready**: Auto-reconnection, error handling, and backoff strategies
-- **Lightweight**: Thin wrapper around `js-streaming` core library
-- **Extensible**: Custom slots and event system for any use case
-
-## 📦 Installation
-
-```bash
-# npm
-npm install vue-streaming js-streaming
-
-# yarn
-yarn add vue-streaming js-streaming
-
-# pnpm
-pnpm add vue-streaming js-streaming
-```
-
-> **Note**: Both `vue-streaming` and `js-streaming` are required. Vue Streaming is a wrapper that leverages the core `js-streaming` library.
-
-### Requirements
-
-- **Vue**: 3.3.0 or higher
-- **Node**: 16+ (for build tools)
-- **Build System**: Vite, Nuxt 3, or Vue CLI with TypeScript support
-
-## 🚀 Quick Start
-
-### Basic WebSocket Example
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const player = ref<InstanceType<typeof StreamPlayer>>();
-const config = {
-  url: "wss://echo.websocket.events",
-  protocols: ["echo-protocol"],
-};
-
-function sendMessage() {
-  player.value?.send("Hello WebSocket!");
-}
-</script>
-
-<template>
-  <div>
-    <h2>WebSocket Demo</h2>
-    <StreamPlayer
-      ref="player"
-      type="websocket"
-      :config="config"
-      :auto-open="true"
-      @message="console.log('Received:', $event)"
-      @status="console.log('Status:', $event)"
-    />
-    <button @click="sendMessage">Send Message</button>
-  </div>
-</template>
-```
-
-### HLS Video Streaming
-
-```vue
-<script setup lang="ts">
-import { StreamPlayer } from "vue-streaming";
-
-const hlsConfig = {
-  url: "https://demo.unified-streaming.com/k8s/features/stable/video/tears-of-steel/tears-of-steel.ism/.m3u8",
-};
-</script>
-
-<template>
-  <StreamPlayer
-    type="hls"
-    :config="hlsConfig"
-    :auto-open="true"
-    :autoplay="true"
-    :controls="true"
-    :muted="false"
-  />
-</template>
-```
-
-### Server-Sent Events
-
-```vue
-<script setup lang="ts">
-import { StreamPlayer } from "vue-streaming";
-
-const sseConfig = {
-  url: "/api/events",
-  headers: { Authorization: "Bearer token" },
-};
-</script>
-
-<template>
-  <StreamPlayer
-    type="sse"
-    :config="sseConfig"
-    :auto-open="true"
-    @message="handleServerEvent"
-  />
-</template>
-```
-
-## 📚 API Reference
-
-### Props
-
-| Prop          | Type         | Default    | Description                                                                |
-| ------------- | ------------ | ---------- | -------------------------------------------------------------------------- |
-| `type`        | `StreamType` | _required_ | Protocol type: `websocket`, `sse`, `http`, `long-polling`, `hls`, `webrtc` |
-| `config`      | `object`     | _required_ | Protocol-specific configuration object                                     |
-| `autoOpen`    | `boolean`    | `false`    | Automatically open connection on mount                                     |
-| `autoplay`    | `boolean`    | `false`    | Auto-play for video streams (HLS/WebRTC)                                   |
-| `controls`    | `boolean`    | `true`     | Show video controls                                                        |
-| `playsInline` | `boolean`    | `true`     | Play video inline on mobile                                                |
-| `muted`       | `boolean`    | `false`    | Start video muted                                                          |
-| `logLimit`    | `number`     | `500`      | Maximum messages to keep in memory                                         |
-| `videoAttrs`  | `object`     | `{}`       | Additional HTML video element attributes                                   |
-
-### Events
-
-| Event      | Payload        | Description                                                               |
-| ---------- | -------------- | ------------------------------------------------------------------------- |
-| `@open`    | `void`         | Connection established                                                    |
-| `@close`   | `void`         | Connection closed                                                         |
-| `@status`  | `StreamStatus` | Status change: `idle`, `connecting`, `open`, `closing`, `closed`, `error` |
-| `@error`   | `Error`        | Error occurred                                                            |
-| `@message` | `any`          | New message/data received                                                 |
-
-### Exposed Methods & Properties
-
-```typescript
-interface StreamPlayerInstance {
-  // Methods
-  open(): Promise<void>;
-  close(): Promise<void>;
-  send(data: unknown): void; // Available for WebSocket/WebRTC
-
-  // Reactive State
-  status: Ref<StreamStatus>;
-  isOpen: Ref<boolean>;
-  error: Ref<Error | null>;
-  messages: Ref<unknown[]>;
-}
-```
-
-### Configuration Objects
-
-Each stream type accepts different configuration options:
-
-#### WebSocket Config
-
-```typescript
-{
-  url: string
-  protocols?: string[]
-  headers?: Record<string, string>
-  binaryType?: 'blob' | 'arraybuffer'
-}
-```
-
-#### SSE Config
-
-```typescript
-{
-  url: string
-  headers?: Record<string, string>
-  withCredentials?: boolean
-  eventSourceInitDict?: EventSourceInit
-}
-```
-
-#### HTTP Streaming Config
-
-```typescript
-{
-  url: string
-  method?: string
-  headers?: Record<string, string>
-  body?: any
-  signal?: AbortSignal
-}
-```
-
-#### Long Polling Config
-
-```typescript
-{
-  url: string
-  interval?: number
-  headers?: Record<string, string>
-  timeout?: number
-}
-```
-
-#### HLS Config
-
-```typescript
-{
-  url: string
-  hlsConfig?: any  // Passed to HLS.js
-}
-```
-
-#### WebRTC Config
-
-```typescript
-{
-  configuration?: RTCConfiguration
-  attachVideo?: boolean  // Auto-attach video stream
-  // Additional WebRTC-specific options
-}
-```
-
-## 🎨 Customization with Slots
-
-### Custom Log Display
-
-```vue
-<template>
-  <StreamPlayer type="websocket" :config="config">
-    <template #log="{ messages, status, error }">
-      <div class="custom-log">
-        <div class="status-bar">
-          Status: <span :class="status">{{ status }}</span>
-        </div>
-        <div v-if="error" class="error">{{ error.message }}</div>
-        <div class="messages">
-          <div v-for="(msg, i) in messages" :key="i" class="message">
-            {{ typeof msg === "string" ? msg : JSON.stringify(msg) }}
-          </div>
-        </div>
-      </div>
-    </template>
-  </StreamPlayer>
-</template>
-
-<style scoped>
-.custom-log {
-  border: 2px solid #007acc;
-  border-radius: 8px;
-  padding: 16px;
-  background: #f8f9fa;
-}
-.status-bar {
-  font-weight: bold;
-}
-.status.open {
-  color: green;
-}
-.status.error {
-  color: red;
-}
-.messages {
-  max-height: 300px;
-  overflow-y: auto;
-}
-.message {
-  padding: 4px 0;
-  border-bottom: 1px solid #eee;
-}
-</style>
-```
-
-### Custom Action Buttons
-
-```vue
-<template>
-  <StreamPlayer type="websocket" :config="config">
-    <template #actions="{ open, close, send, isOpen, status }">
-      <div class="action-bar">
-        <button @click="open" :disabled="isOpen">Connect</button>
-        <button @click="close" :disabled="!isOpen">Disconnect</button>
-        <button @click="send('ping')" :disabled="!isOpen">Ping</button>
-        <span class="status-indicator" :class="status">{{ status }}</span>
-      </div>
-    </template>
-  </StreamPlayer>
-</template>
-```
-
-## 🛠️ Advanced Usage
-
-### Auto-Reconnection and Error Handling
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const config = ref({
-  url: "wss://api.example.com/ws",
-  // Auto-reconnection settings
-  autoReconnect: true,
-  maxRetries: 5,
-  heartbeatMs: 30000,
-  backoff: {
-    baseMs: 1000,
-    maxMs: 10000,
-    factor: 1.5,
-    jitter: true,
-  },
-});
-
-function handleError(error: Error) {
-  console.error("Stream error:", error);
-  // Custom error handling logic
-}
-
-function handleStatusChange(status: string) {
-  if (status === "error") {
-    // Handle connection errors
-  } else if (status === "open") {
-    console.log("Successfully connected!");
-  }
-}
-</script>
-
-<template>
-  <StreamPlayer
-    type="websocket"
-    :config="config"
-    @error="handleError"
-    @status="handleStatusChange"
-  />
-</template>
-```
-
-### Dynamic Configuration
-
-```vue
-<script setup lang="ts">
-import { ref, computed } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const apiEndpoint = ref("wss://api.example.com");
-const authToken = ref("");
-
-const dynamicConfig = computed(() => ({
-  url: `${apiEndpoint.value}/ws`,
-  headers: {
-    Authorization: `Bearer ${authToken.value}`,
-  },
-}));
-
-// Configuration changes will automatically recreate the stream
-</script>
-
-<template>
-  <div>
-    <input v-model="apiEndpoint" placeholder="WebSocket URL" />
-    <input v-model="authToken" placeholder="Auth Token" />
-
-    <StreamPlayer
-      type="websocket"
-      :config="dynamicConfig"
-      :auto-open="!!authToken"
-    />
-  </div>
-</template>
-```
-
-### Programmatic Control
-
-```vue
-<script setup lang="ts">
-import { ref, onMounted } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const player = ref<InstanceType<typeof StreamPlayer>>();
-
-onMounted(() => {
-  // Programmatic control
-  setTimeout(() => {
-    player.value?.open();
-  }, 1000);
-
-  // Send periodic messages
-  setInterval(() => {
-    if (player.value?.isOpen) {
-      player.value.send({
-        type: "heartbeat",
-        timestamp: Date.now(),
-      });
-    }
-  }, 10000);
-});
-
-// Access reactive state
-const connectionStatus = computed(() => player.value?.status || "idle");
-const messageCount = computed(() => player.value?.messages.length || 0);
-</script>
-```
-
-## 🔧 TypeScript Support
-
-Vue Streaming is fully typed. Import types for enhanced development experience:
-
-```typescript
-import type {
-  StreamType,
-  StreamStatus,
-  StreamState,
-  StreamAPI,
-} from "vue-streaming";
-
-// Component instance type
-import { StreamPlayer } from "vue-streaming";
-type StreamPlayerInstance = InstanceType<typeof StreamPlayer>;
-
-// Usage in composition function
-function useStreamPlayer() {
-  const player = ref<StreamPlayerInstance>();
-  const status = computed(() => player.value?.status || "idle");
-
-  return { player, status };
-}
-```
-
-## 🌐 Nuxt 3 / SSR Usage
-
-For server-side rendering, wrap the component to prevent hydration issues:
-
-```vue
-<template>
-  <div>
-    <ClientOnly>
-      <StreamPlayer type="websocket" :config="config" :auto-open="true" />
-      <template #fallback>
-        <div>Loading stream player...</div>
-      </template>
-    </ClientOnly>
-  </div>
-</template>
-```
-
-Or create an async component:
-
-```vue
-<script setup lang="ts">
-import { defineAsyncComponent } from "vue";
-
-const StreamPlayer = defineAsyncComponent(() =>
-  import("vue-streaming").then((m) => m.StreamPlayer)
-);
-</script>
-```
-
-## 📱 Real-World Examples
-
-### Chat Application
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const message = ref("");
-const chatPlayer = ref<InstanceType<typeof StreamPlayer>>();
-
-const config = {
-  url: "wss://chat.example.com/ws",
-  protocols: ["chat-v1"],
-};
-
-function sendMessage() {
-  if (message.value.trim()) {
-    chatPlayer.value?.send({
-      type: "message",
-      content: message.value,
-      timestamp: new Date().toISOString(),
-    });
-    message.value = "";
-  }
-}
-
-function handleChatMessage(msg: any) {
-  if (msg.type === "message") {
-    // Handle incoming chat message
-    console.log(`${msg.user}: ${msg.content}`);
-  }
-}
-</script>
-
-<template>
-  <div class="chat-container">
-    <StreamPlayer
-      ref="chatPlayer"
-      type="websocket"
-      :config="config"
-      :auto-open="true"
-      @message="handleChatMessage"
-    >
-      <template #log="{ messages }">
-        <div class="chat-messages">
-          <div v-for="msg in messages" :key="msg.id" class="message">
-            <strong>{{ msg.user }}:</strong> {{ msg.content }}
-          </div>
-        </div>
-      </template>
-
-      <template #actions="{ isOpen }">
-        <div class="chat-input">
-          <input
-            v-model="message"
-            @keyup.enter="sendMessage"
-            :disabled="!isOpen"
-            placeholder="Type a message..."
-          />
-          <button @click="sendMessage" :disabled="!isOpen">Send</button>
-        </div>
-      </template>
-    </StreamPlayer>
-  </div>
-</template>
-```
-
-### Live Data Dashboard
-
-```vue
-<script setup lang="ts">
-import { ref, computed } from "vue";
-import { StreamPlayer } from "vue-streaming";
-
-const metrics = ref<any[]>([]);
-
-const config = {
-  url: "/api/metrics/stream",
-  headers: { Accept: "text/event-stream" },
-};
-
-function handleMetricsUpdate(data: any) {
-  if (data.type === "metrics") {
-    metrics.value = [...metrics.value, data.payload].slice(-50); // Keep last 50
-  }
-}
-
-const latestMetrics = computed(
-  () => metrics.value[metrics.value.length - 1]?.payload || {}
-);
-</script>
-
-<template>
-  <div class="dashboard">
-    <h1>Live Metrics Dashboard</h1>
-
-    <div class="metrics-grid">
-      <div class="metric-card">
-        <h3>CPU Usage</h3>
-        <div class="metric-value">{{ latestMetrics.cpu }}%</div>
-      </div>
-      <div class="metric-card">
-        <h3>Memory</h3>
-        <div class="metric-value">{{ latestMetrics.memory }}MB</div>
-      </div>
-    </div>
-
-    <StreamPlayer
-      type="sse"
-      :config="config"
-      :auto-open="true"
-      @message="handleMetricsUpdate"
-    >
-      <template #log="{ messages, status }">
-        <div class="connection-status">
-          Status: <span :class="status">{{ status }}</span> | Updates:
-          {{ messages.length }}
-        </div>
-      </template>
-    </StreamPlayer>
-  </div>
-</template>
-```
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Connection fails immediately**
-
-```typescript
-// Check if the URL is correct and accessible
-const config = {
-  url: "ws://localhost:3000/ws", // http:// for ws://, https:// for wss://
-};
-```
-
-**CORS issues with SSE/HTTP**
-
-```typescript
-const config = {
-  url: "/api/stream",
-  headers: {
-    "Access-Control-Allow-Origin": "*",
-  },
-};
-```
-
-**Video not playing (HLS/WebRTC)**
-
-```vue
-<StreamPlayer
-  type="hls"
-  :config="hlsConfig"
-  :autoplay="true"
-  :muted="true"  <!-- Required for autoplay in most browsers -->
-  :plays-inline="true"
-/>
-```
-
-**Messages not displaying**
-
-```javascript
-// Check if logLimit is sufficient
-<StreamPlayer :log-limit="1000" />
-
-// Or handle messages manually
-@message="msg => console.log('Received:', msg)"
-```
-
-### Browser Compatibility
-
-- **WebSocket**: All modern browsers
-- **SSE**: All modern browsers (IE/Edge requires polyfill)
-- **HLS**: Requires HLS.js for non-Safari browsers
-- **WebRTC**: Modern browsers (check specific API support)
-
-### Performance Tips
-
-1. **Limit message history**: Use reasonable `logLimit` values
-2. **Debounce rapid updates**: Use `shallowRef` for message arrays
-3. **Clean up properly**: Component handles cleanup automatically
-4. **Use object URLs**: For large binary data in WebRTC/HLS
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Setup
-
-```bash
-git clone https://github.com/yourusername/vue-streaming.git
-cd vue-streaming
-npm install
-npm run dev
-```
-
-### Building
-
-```bash
-npm run build
-npm run test
-```
-
-## 📄 License
-
-MIT © Vue Streaming Contributors
-
----
-
-<div align="center">
-
-**[Documentation](https://github.com/yourusername/vue-streaming#readme) • [Examples](https://github.com/yourusername/vue-streaming/tree/main/examples) • [Issues](https://github.com/yourusername/vue-streaming/issues)**
-
-Made with ❤️ for the Vue.js community
-
-</div>
+# vue-streaming
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/keroloszakaria/vue-streaming">
+    <img src="https://img.shields.io/npm/v/keroloszakaria/vue-streaming.svg" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/keroloszakaria/vue-streaming">
+    <img src="https://img.shields.io/npm/dm/keroloszakaria/vue-streaming.svg" alt="npm downloads" />
+  </a>
+  <a href="https://vuejs.org/">
+    <img src="https://img.shields.io/badge/Vue-3.3%2B-brightgreen.svg" alt="Vue 3" />
+  </a>
+  <a href="https://www.typescriptlang.org/">
+    <img src="https://img.shields.io/badge/TypeScript-Ready-blue.svg" alt="TypeScript" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License" />
+  </a>
+</p>
+
+<p align="center">
+  Comprehensive <b>Vue 3 streaming library</b> with composables for WebSocket, Socket.IO, HLS, Laravel Echo, WebRTC, Point Cloud, and Data Streaming.
+</p>
+
+---
+
+## Features
+
+- **useWebSocket** - Native WebSocket with auto-reconnect and heartbeat
+- **useSocketIO** - Full Socket.IO support with rooms and events
+- **useHLS** - HTTP Live Streaming with quality control
+- **useLaravelEcho** - Pusher/Reverb broadcasting integration
+- **useWebRTC** - Peer connections with data channels for point cloud/detection
+- **usePointCloud** - LiDAR/3D point cloud streaming and decoding
+- **useDataStream** - Generic data streaming with buffering and deduplication
+- **Components** - StreamViewer, HLSPlayer, PointCloudViewer, WebRTCViewer
+- **TypeScript** - Full TypeScript support with exported types
+- **Tree-shakeable** - Import only what you need
+
+---
+
+## Installation
+
+`bash
+npm install vue-streaming
+
+# yarn
+
+yarn add vue-streaming
+
+# pnpm
+
+pnpm add vue-streaming
+`
+
+### Optional Dependencies
+
+Install based on the features you need:
+
+`bash
+
+# For HLS streaming
+
+npm install hls.js
+
+# For Socket.IO
+
+npm install socket.io-client
+
+# For Laravel Echo
+
+npm install laravel-echo pusher-js
+
+# For Point Cloud visualization
+
+npm install three @types/three
+
+# For DRACO compression
+
+npm install draco3d
+`
+
+---
+
+## Quick Start
+
+### WebSocket
+
+`vue
+
+<script setup lang="ts">
+import { useWebSocket } from 'vue-streaming'
+
+const { isConnected, lastMessage, connect, send, disconnect } = useWebSocket({
+  url: 'wss://example.com/ws',
+  autoConnect: true,
+  autoReconnect: true
+}, {
+  onMessage: (data) => console.log('Received:', data)
+})
+</script>
+
+`
+
+### Socket.IO
+
+`vue
+
+<script setup lang="ts">
+import { useSocketIO } from 'vue-streaming'
+
+const { isConnected, connect, emit, on } = useSocketIO({
+  url: 'https://example.com',
+  autoConnect: true
+})
+
+// Listen to events
+on('chat:message', (msg) => console.log(msg))
+
+// Emit events
+emit('chat:send', { text: 'Hello!' })
+</script>
+
+`
+
+### HLS Streaming
+
+`vue
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { useHLS } from 'vue-streaming'
+
+const videoRef = ref<HTMLVideoElement | null>(null)
+
+const { attach, play, levels, setLevel } = useHLS({
+  url: 'https://example.com/stream.m3u8',
+  autoPlay: true
+})
+
+onMounted(() => {
+  if (videoRef.value) {
+    attach(videoRef.value)
+  }
+})
+</script>
+
+<template>
+  <video ref="videoRef" controls />
+</template>
+`
+
+### Laravel Echo
+
+`vue
+
+<script setup lang="ts">
+import { useLaravelEcho } from 'vue-streaming'
+
+const { channel, privateChannel, presenceChannel } = useLaravelEcho({
+  broadcaster: 'pusher',
+  key: 'your-pusher-key',
+  cluster: 'mt1'
+})
+
+// Public channel
+const chat = channel('chat')
+chat.listen('MessageSent', (e) => console.log(e))
+
+// Private channel
+const user = privateChannel('user.1')
+user.listen('NotificationReceived', (e) => console.log(e))
+
+// Presence channel
+const room = presenceChannel('room.1')
+room.here((users) => console.log('Online:', users))
+room.joining((user) => console.log('Joined:', user))
+room.leaving((user) => console.log('Left:', user))
+</script>
+
+`
+
+### WebRTC with Point Cloud
+
+`vue
+
+<script setup lang="ts">
+import { useWebRTC } from 'vue-streaming'
+
+const { 
+  isRunning, 
+  connectionState, 
+  lastPointCloudFrame,
+  lastBoundingBoxes,
+  start, 
+  stop 
+} = useWebRTC({
+  signalingUrl: 'wss://example.com/signaling',
+  enablePointCloud: true,
+  enableDetections: true
+}, {
+  onPointCloudFrame: (frame) => {
+    console.log(Received ${frame.points.length} points)
+  },
+  onBoundingBoxData: (boxes) => {
+    console.log(Received ${boxes.length} detections)
+  }
+})
+</script>
+
+`
+
+### Point Cloud Decoding
+
+`vue
+
+<script setup lang="ts">
+import { usePointCloud } from 'vue-streaming'
+
+const { decode, points, bounds, isDecoding } = usePointCloud({
+  format: 'auto',
+  maxPoints: 100000,
+  downsampleFactor: 2
+})
+
+// Decode point cloud data
+const result = await decode(arrayBuffer)
+console.log(Decoded ${result.points.length} points)
+</script>
+
+`
+
+### Data Streaming
+
+`vue
+
+<script setup lang="ts">
+import { useDataStream } from 'vue-streaming'
+
+interface SensorData {
+  id: string
+  value: number
+  timestamp: number
+}
+
+const { data, buffer, push, subscribe, stats } = useDataStream<SensorData>({
+  bufferSize: 1000,
+  deduplicate: true,
+  deduplicateKey: 'id',
+  throttleMs: 100
+})
+
+// Subscribe to data
+subscribe((item) => console.log('New data:', item))
+
+// Push data manually
+push({ id: 'sensor-1', value: 42, timestamp: Date.now() })
+</script>
+
+`
+
+---
+
+## Components
+
+### StreamViewer
+
+Generic stream viewer for displaying real-time data:
+
+`vue
+<template>
+  <StreamViewer
+    :data="streamData"
+    :max-lines="100"
+    :auto-scroll="true"
+    :show-timestamps="true"
+  />
+</template>
+`
+
+### HLSPlayer
+
+HLS video player with quality controls:
+
+`vue
+<template>
+  <HLSPlayer
+    src="https://example.com/stream.m3u8"
+    :auto-play="true"
+    :controls="true"
+    :low-latency="true"
+    @ready="onReady"
+    @level-change="onQualityChange"
+  />
+</template>
+`
+
+### PointCloudViewer
+
+3D point cloud visualization (requires three.js):
+
+`vue
+<template>
+  <PointCloudViewer
+    :points="pointCloudData"
+    :point-size="0.02"
+    :auto-rotate="true"
+    :show-grid="true"
+  />
+</template>
+`
+
+### WebRTCViewer
+
+WebRTC stream viewer with connection controls:
+
+`vue
+<template>
+  <WebRTCViewer
+    signaling-url="wss://example.com/signaling"
+    :enable-point-cloud="true"
+    :enable-detections="true"
+    :auto-connect="true"
+    @pointcloud="onPointCloud"
+    @detections="onDetections"
+  />
+</template>
+`
+
+---
+
+## API Reference
+
+### useWebSocket
+
+| Option                 | Type                 | Default  | Description                  |
+| ---------------------- | -------------------- | -------- | ---------------------------- |
+| `url`                  | `string`             | required | WebSocket URL                |
+| `protocols`            | `string \| string[]` | -        | Subprotocols                 |
+| `autoConnect`          | `boolean`            | `true`   | Auto-connect on mount        |
+| `autoReconnect`        | `boolean`            | `true`   | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `number`             | `5`      | Max reconnection attempts    |
+| `reconnectDelay`       | `number`             | `1000`   | Initial reconnect delay (ms) |
+| `heartbeatInterval`    | `number`             | -        | Heartbeat interval (ms)      |
+
+### useSocketIO
+
+| Option        | Type      | Default  | Description              |
+| ------------- | --------- | -------- | ------------------------ |
+| `url`         | `string`  | required | Server URL               |
+| `options`     | `object`  | -        | Socket.IO client options |
+| `autoConnect` | `boolean` | `true`   | Auto-connect on mount    |
+
+### useHLS
+
+| Option           | Type      | Default  | Description                   |
+| ---------------- | --------- | -------- | ----------------------------- |
+| `url`            | `string`  | required | HLS manifest URL              |
+| `autoPlay`       | `boolean` | `true`   | Auto-play on attach           |
+| `lowLatencyMode` | `boolean` | `false`  | Enable low-latency mode       |
+| `startLevel`     | `number`  | `-1`     | Initial quality (-1 for auto) |
+
+### useLaravelEcho
+
+| Option        | Type                                  | Default  | Description      |
+| ------------- | ------------------------------------- | -------- | ---------------- |
+| `broadcaster` | `'pusher' \| 'socket.io' \| 'reverb'` | required | Broadcaster type |
+| `key`         | `string`                              | -        | Pusher app key   |
+| `cluster`     | `string`                              | -        | Pusher cluster   |
+| `wsHost`      | `string`                              | -        | WebSocket host   |
+| `wsPort`      | `number`                              | -        | WebSocket port   |
+
+### useWebRTC
+
+| Option             | Type             | Default  | Description                |
+| ------------------ | ---------------- | -------- | -------------------------- |
+| `signalingUrl`     | `string`         | required | Signaling server URL       |
+| `iceServers`       | `RTCIceServer[]` | STUN     | ICE servers                |
+| `enablePointCloud` | `boolean`        | `true`   | Enable point cloud channel |
+| `enableDetections` | `boolean`        | `true`   | Enable detection channel   |
+
+### usePointCloud
+
+| Option             | Type               | Default  | Description           |
+| ------------------ | ------------------ | -------- | --------------------- |
+| `format`           | `PointCloudFormat` | `'auto'` | Point cloud format    |
+| `maxPoints`        | `number`           | -        | Max points to decode  |
+| `downsampleFactor` | `number`           | `1`      | Downsample factor     |
+| `dracoPath`        | `string`           | -        | Path to DRACO decoder |
+
+### useDataStream
+
+| Option        | Type      | Default | Description              |
+| ------------- | --------- | ------- | ------------------------ |
+| `bufferSize`  | `number`  | `1000`  | Max buffer size          |
+| `throttleMs`  | `number`  | -       | Throttle interval        |
+| `deduplicate` | `boolean` | `false` | Enable deduplication     |
+| `batchSize`   | `number`  | -       | Batch size for callbacks |
+
+---
+
+## Legacy Support
+
+The package still exports the legacy `StreamPlayer` component for backward compatibility:
+
+`vue
+
+<script setup>
+import { StreamPlayer } from 'vue-streaming'
+</script>
+
+<template>
+  <StreamPlayer
+    type="websocket"
+    :config="{ url: 'wss://example.com' }"
+    :auto-open="true"
+  />
+</template>
+`
+
+---
+
+## License
+
+MIT (c) [Kerolos Zakaria](https://keroloszakaria.surge.sh)