v-pip
Version:
Vue 3 wrapper for the native Picture-in-Picture (PiP) Web API — floating video, document PiP, and TypeScript-first composables.
282 lines (213 loc) • 9.54 kB
Markdown
# [V-pip 🖼](https://github.com/vinayakkulkarni/v-pip#readme)
<!-- Badges -->
[](https://github.com/vinayakkulkarni/v-pip/actions/workflows/pipeline.yml)
[](https://github.com/geoql/doctor)
[](https://github.com/vinayakkulkarni/v-pip/releases)
[](https://www.npmjs.com/package/v-pip)
[](https://jsr.io/@vinayakkulkarni/v-pip)
[](http://npm-stat.com/charts.html?package=v-pip)
[](https://bundlephobia.com/package/v-pip@latest)
[](https://github.com/vinayakkulkarni/v-pip/blob/main/package.json)
[](./LICENSE)
[](https://github.com/voidzero-dev/vite-plus)
[](https://www.typescriptlang.org/)
[](https://pnpm.io/)
[](https://nodejs.org/)
<!-- End Badges -->
**[Live demo][demo]** · [npm][npm] · [JSR][jsr]
---
## Demo
Live demo: [v-pip.vinayakkulkarni.dev][demo]
---
## Features
- Vue 💚 Picture-in-picture!
- Built from scratch using [TypeScript](https://www.typescriptlang.org)
---
### Versions
- For Vue 3.x version – `pnpm add v-pip`
- For Vue 2.x version – `pnpm add v-pip@1`
## Table of Contents
- [V-pip 🖼](#v-pip-)
- [Demo](#demo)
- [Features](#features)
- [Versions](#versions)
- [Table of Contents](#table-of-contents)
- [Demo](#demo-1)
- [Requirements](#requirements)
- [Installation](#installation)
- [Build Setup](#build-setup)
- [Usage](#usage)
- [Globally](#globally)
- [As a component](#as-a-component)
- [As a plugin](#as-a-plugin)
- [Locally](#locally)
- [HTML](#html)
- [JS](#js)
- [HTML](#html-1)
- [JS](#js-1)
- [Props](#props)
- [Events](#events)
- [Contributing](#contributing)
- [Author](#author)
- [License](#license)
## Demo
[v-pip.vinayakkulkarni.dev][demo]: a Nuxt app on
Cloudflare Workers. Source in [`example/`](./example).
## Requirements
- [vue](https://vuejs.org/) `^3.x`
### Installation
```bash
pnpm add v-pip # pnpm add v-pip
```
CDN: [UNPKG](https://unpkg.com/v-pip/dist/) | [jsDelivr](https://cdn.jsdelivr.net/npm/v-pip/dist/) (available as `window.VPip`)
### Build Setup
```bash
# install dependencies
$ pnpm install --frozen-lockfile
# package the library
$ pnpm run build
# run the demo locally
$ pnpm run dev
# deploy the demo to Cloudflare Workers (v-pip.vinayakkulkarni.dev)
$ pnpm run deploy
```
## Usage
### Globally
#### As a component
```javascript
import { VPip } from 'v-pip';
Vue.component('VPip', VPip);
```
#### As a plugin
```javascript
import Vue from 'vue';
import VPip from 'v-pip';
Vue.use(VPip);
```
### Locally
```javascript
import { VPip } from 'v-pip';
```
<details>
<summary>
Example 1 (full demo: example/app/components/PipPlayground.vue)
</summary>
### HTML
```html
<v-pip
:video-options="videoOptions"
:button-options="buttonOptions"
@video-in-pip="handlePIP"
@requesting-pip-failure="handlePipOpenFailure"
@exiting-pip-failure="handlePipExitFailure"
/>
```
### JS
```javascript
import { VPip } from 'v-pip';
Vue.component('example-component', {
components: {
VPip,
},
data: () => ({
isPip: false,
videoOptions: {
src: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
poster:
'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg',
wrapper: '',
class: '',
height: '',
width: '',
},
buttonOptions: {
wrapper: '',
type: 'button',
class: '',
label: 'Toggle picture-in-picture',
},
}),
methods: {
handlePIP(e) {
this.isPip = e;
},
handlePipOpenFailure(err) {
console.log('Video failed to enter Picture-in-Picture mode.', err);
},
handlePipExitFailure(err) {
console.log('Video failed to leave Picture-in-Picture mode.', err);
},
},
});
```
</details>
<details>
<summary>
<em>Example 2 (minimal)</em>
</summary>
### HTML
```html
<v-pip :video-options="videoOptions" />
```
### JS
```javascript
import { VPip } from 'v-pip';
Vue.component('example-component', {
components: {
VPip,
},
data: () => ({
videoOptions: {
src: 'http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
},
}),
});
```
</details>
### Props
| Name | Type | Required? | Description |
| ---------------- | ------ | --------- | --------------------------------------------------------- |
| `video-options` | Object | Yes | The set of options required to setup the V-Pip component. |
| `button-options` | Object | No | The set of options for the toggle button |
### Events
| Name | Description |
| ------------------------ | ------------------------------------------------------------------------ |
| `video-in-pip` | Emits an `Boolean` whether the Video is in PIP or not |
| `requesting-pip-failure` | Emits an `Object` when the video fails to enter Picture-in-Picture mode. |
| `exiting-pip-failure` | Emits an `Object` when the video fails to leave Picture-in-Picture mode. |
## Contributing
1. Fork it ( [https://github.com/vinayakkulkarni/v-pip/fork](https://github.com/vinayakkulkarni/v-pip/fork) )
2. Create your feature branch (`git checkout -b feat/new-feature`)
3. Commit your changes (`git commit -Sam 'feat: add feature'`)
4. Push to the branch (`git push origin feat/new-feature`)
5. Create a new [Pull Request](https://github.com/vinayakkulkarni/v-pip/compare)
_Note_:
1. Please contribute using [GitHub Flow](https://web.archive.org/web/20191104103724/https://guides.github.com/introduction/flow/)
2. Commits & PRs will be allowed only if the commit messages & PR titles follow the [conventional commit standard](https://www.conventionalcommits.org/), _read more about it [here](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional#type-enum)_
3. PS. Ensure your commits are signed. _[Read why](https://withblue.ink/2020/05/17/how-and-why-to-sign-git-commits.html)_
## Author
**v-pip** © [Vinayak](https://vinayakkulkarni.dev), Released under the [MIT](./LICENSE) License.<br>
Authored and maintained by Vinayak Kulkarni with help from contributors ([list](https://github.com/vinayakkulkarni/v-pip/contributors)).
> [vinayakkulkarni.dev](https://vinayakkulkarni.dev) · GitHub [@vinayakkulkarni](https://github.com/vinayakkulkarni) · Twitter [@\_vinayak_k](https://twitter.com/_vinayak_k)
## License
[](https://app.fossa.io/projects/git%2Bgithub.com%2Fvinayakkulkarni%2Fv-pip?ref=badge_large)
## More from the author
- [v-clappr][v-clappr] — Vue 3 wrapper for the Clappr media player
- [v-image][v-image] — Vue 3 image input with live preview
- [v-spotlight][v-spotlight] — cursor spotlight overlay for Vue 3
- [v-intl][v-intl] — native `Intl` formatting components for Vue 3
- [nxui][nxui] — animated UI components and Paper Shaders for Vue and Nuxt
- [shadscan-vue][shadscan-vue] — UI audits for shadcn-vue and shadcn-nuxt apps
See every project at [vinayakkulkarni.dev/projects][projects]
and [geoql.in][geoql-in].
[demo]: https://v-pip.vinayakkulkarni.dev/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[npm]: https://www.npmjs.com/package/v-pip
[jsr]: https://jsr.io/@vinayakkulkarni/v-pip
[v-clappr]: https://v-clappr.vinayakkulkarni.dev/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[v-image]: https://v-image.vinayakkulkarni.dev/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[v-spotlight]: https://v-spotlight.vinayakkulkarni.dev/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[v-intl]: https://v-intl.vinayakkulkarni.dev/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[nxui]: https://nxui.geoql.in/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[shadscan-vue]: https://shadscan-vue.geoql.in/?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[projects]: https://vinayakkulkarni.dev/projects?utm_source=github&utm_medium=readme&utm_campaign=v-pip
[geoql-in]: https://geoql.in/?utm_source=github&utm_medium=readme&utm_campaign=v-pip