# yt-search

> search youtube

Latest version **2.13.1** (published 2025-05-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install yt-search
pnpm add yt-search
yarn add yt-search
bun add yt-search
```

Provides the commands `yt-search`, `yt-search-audio`, `yt-search-video`.

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.13.1 |
| Published | 2025-05-02 |
| First published | 2016-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/yt-search) |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 54.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 121 |
| Author | talmobi |
| Maintainers | talmobi |

## Links

- npm: https://www.npmjs.com/package/yt-search
- Repository: https://github.com/talmobi/yt-search
- Homepage: https://github.com/talmobi/yt-search#readme
- Issues: https://github.com/talmobi/yt-search/issues
- npm.io page: https://npm.io/package/yt-search

## Dependencies (8)

- [dasu](https://npm.io/package/dasu.md) ~0.4.3
- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.10
- [minimist](https://npm.io/package/minimist.md) ~1.2.5
- [node-fzf](https://npm.io/package/node-fzf.md) ~0.14.0
- [boolstring](https://npm.io/package/boolstring.md) ~2.0.1
- [human-time](https://npm.io/package/human-time.md) 0.0.2
- [jsonpath-plus](https://npm.io/package/jsonpath-plus.md) ~10.3.0
- [async.parallellimit](https://npm.io/package/async.parallellimit.md) ~0.5.2

## Recent versions

- 2.13.1 (latest) — 2025-05-02
- 2.13.0 — 2025-05-02
- 2.12.1 — 2024-08-20
- 2.12.0 — 2024-08-19
- 2.11.1 — 2024-07-01
- 2.11.0 — 2024-05-07
- 2.10.4 — 2023-01-15
- 2.10.3 — 2021-12-30
- 2.10.2 — 2021-10-13
- 2.10.1 — 2021-08-15
- 2.10.0 — 2021-07-26
- 2.9.0 — 2021-06-19
- 2.8.0 — 2021-04-17
- 2.7.7 — 2021-04-17
- 2.7.6 — 2021-04-01
- … 59 more at https://npm.io/package/yt-search/versions

## README

[![npm](https://img.shields.io/npm/v/yt-search.svg?maxAge=3600)](https://www.npmjs.com/package/yt-search)
[![npm](https://img.shields.io/npm/dm/yt-search.svg?maxAge=3600)](https://www.npmjs.com/package/yt-search)
[![npm](https://img.shields.io/npm/l/yt-search.svg?maxAge=3600)](https://www.npmjs.com/package/yt-search)
![mac](https://github.com/talmobi/yt-search/actions/workflows/mac-nodejs.yml/badge.svg?branch=master)
![ubuntu](https://github.com/talmobi/yt-search/actions/workflows/ubuntu-nodejs.yml/badge.svg?branch=master)
![windows](https://github.com/talmobi/yt-search/actions/workflows/windows-nodejs.yml/badge.svg?branch=master)

#  yt-search
simple youtube search API and CLI

![](https://thumbs.gfycat.com/ContentShockingCuttlefish-size_restricted.gif)

## Installation
```bash
npm install yt-search # local module usage
```

## Easy to use
```javascript
const yts = require( 'yt-search' )
const r = await yts( 'superman theme' )

const videos = r.videos.slice( 0, 3 )
videos.forEach( function ( v ) {
	const views = String( v.views ).padStart( 10, ' ' )
	console.log( `${ views } | ${ v.title } (${ v.timestamp }) | ${ v.author.name }` )
} )
```

###### output
```javascript
  38878009 | Superman Theme (4:13) | Super Man
   8861479 | Superman • Main Theme • John Williams (4:26) | HD Film Tributes
   7802473 | Superman - Main Theme (BBC Proms) (4:46) | brassbone player
```

###### try it
https://runkit.com/talmobi/runkit-npm-yt-search-basic

#### single video
```javascript
const video = await yts( { videoId: '_4Vt0UGwmgQ' } )
console.log( video.title + ` (${ video.duration.timestamp })` )
```
###### output
```javascript
Philip Glass. -  Koyaanisqatsi (original version) (3:29)
```

###### try it
https://runkit.com/talmobi/runkit-npm-yt-search-video

#### single playlist
```javascript
const list = await yts( { listId: 'PL7k0JFoxwvTbKL8kjGI_CaV31QxCGf1vJ' } )

console.log( 'playlist title: ' + list.title )
list.videos.forEach( function ( video ) {
	console.log( video.title )
} )
```
###### output
```javascript
playlist title: Superman Themes
The Max Fleischer Cartoon (From "Superman")
[Deleted video]
Superman Theme
[Private video]
Superman The Animated Series Full Theme
Smallville theme song
Reprise / Fly Away
Superman Doomsday Soundtrack- Main Title
Hans Zimmer - Man of Steel Theme
Supergirl CW Soundtrack - Superman Theme Extended
```

###### try it
https://runkit.com/talmobi/runkit-npm-yt-search-playlist

## CLI Usage (interactive)
```bash
yt-search superman theme
```

If you have `mpv` installed, yt-search can directly play yt videos (or audio only)
```bash
yt-search-video Dank Memes Videos
yt-search-audio Wagner
```

If you don't have `mpv` installed, you can alternatively try installing `yt-play-cli`
```bash
npm install -g yt-play-cli
```

see: https://github.com/talmobi/yt-play


## About
Simple function to get youtube search results.

## Why
Not sure..

## How
Using HTTP requests and parsing the results with [cheerio](https://github.com/cheeriojs/cheerio).

CLI interactive mode with [node-fzf](https://github.com/talmobi/node-fzf)

## Options
```bash
var opts = { query: 'superman theme' }
yts( opts, function ( err, r ) {
	if ( err ) throw err
	console.log( r.videos ) // video results
	console.log( r.playlists ) // playlist results
	console.log( r.channels ) // channel results
	console.log( r.live ) // live stream results
} )

var opts = { videoId: 'e9vrfEoc8_g' }
yts( opts, function ( err, video ) {
	if ( err ) throw err
	console.log( video ) // single video metadata
} )

var opts = { listId: 'PL7k0JFoxwvTbKL8kjGI_CaV31QxCGf1vJ' }
yts( opts, function ( err, playlist ) {
	if ( err ) throw err
	console.log( playlist ) // single playlist metadata
	console.log( playlist.videos ) // playlist videos
} )
```

## Alternatives
[ytsr](https://www.npmjs.com/package/ytsr)

## Test
```
npm test
```

## Development / Debugging
Modify `debug.js` by adding another mXX function and calling it at the top.

Run with the debug flag ex: `DEBUG=1 node debug.js`

The HTML response received by yt-search is written to `dasu.response`.

Prettify `dasu.response` for easier debugging ex: `prettier --parser html`
-- save it as a temporary file so it's not overwritten when you call the
debug fn again if necessary ex: `pewdiepie.channel` or `superman.results`

Most/all relevant data for parsing is found in the results inside the
`ytInitialData` object.

We're using `jsonpath-plus` for resilient parsing of the `ytInitialData`
object that is subject to continuous modifications by YouTube.

---
_Source: https://npm.io/package/yt-search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._