dart_holodex_api - Dart API docs

A Dart wrapper for Holodex API v2

Features
Getting started
Usage
Additional information

Features

Use this plugin in your Flutter app to:

Built in http client, or you can pass in your own
Enum and classes built in so that you don't need to consult the official Holodex API documentation
Get a video by its ID
Get a list of videos
Get a list of live videos
Get a channel by its ID
Get a list of channels
Quickly Access Live / Upcoming for a set of Channels
Get Videos Related To Channel
Get Clips of a VTuber
Get Collabs that mention a VTuber
Get Videos From Channel
Get a single Video's metadata
Search videos
Search for videos with comment

Getting started

Get an API key at holodex.net, instructions here

Add this to your pubspec.yaml file

dependencies:
    dart_holodex_api: ^0.2.1

Then run dart pub get or flutter pub get.

Usage

Full example.

Get an instance of HolodexClient with your API key

final HolodexClient holodexClient = HolodexClient(apiKey: apiKey);

Remember to close the client when you are done with it. This closes the client and cleans up any resources associated with it.

It's important to close the client when it's done being used; failing to do so can cause the Dart process to hang.

holodexClient.close();

Get a video by its ID

Returns VideoFull

Arguments:

videoId The video ID as a string
includes Request extra data be included in the results. They are not guarenteed to be returned.

// Get one video and print it
final VideoFull video = await holodexClient.getVideoFromId(
    'Gx_GPwpyLxw',
    includes: <Includes>[
        Includes.channelStats,
        Includes.clips,
        Includes.description,
        Includes.liveInfo,
        Includes.mentions,
        Includes.refers,
        Includes.simulcasts,
        Includes.songs,
        Includes.sources,
    ],
);
print(video.toString());

Get a list of videos

Returns VideoFullList

Arguments:

channelId Filter by video uploader channel ID
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang Filter by the Language
limit Limit the number of results returned. Maximum value of 50
maxUpcomingHours Number of maximum hours upcoming to get upcoming videos by (for rejecting waiting rooms that are two years out)
mentionedChannelId Filter by mentioned channel id, excludes itself. Generally used to find collabs/clips that include the requested channel
offset Receive results starting at this number in the array from the Holodex API
order Order results by ascending or descending
organization Filter by clips that feature the org's talent or videos posted by the org's talent.
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.
sort Sort the returned data by this field
status Filter by the video status
topic Filter by video topic ID
type Filter by type of video, either clips or streams

// Get a bunch of videos and print them
final VideoFullList videoList = await holodexClient.getVideos(
    channelId: 'UCsYcCwDqv6Sg8KMIIMF54SA', // Kiriku Translation
    includes: <Includes>[
        Includes.channelStats,
        Includes.clips,
        Includes.description,
        Includes.liveInfo,
        Includes.mentions,
        Includes.refers,
        Includes.simulcasts,
        Includes.songs,
        Includes.sources,
    ],
    lang: <Language>[Language.all],
    limit: 25,
    maxUpcomingHours: 1000,
    mentionedChannelId: 'UCDqI2jOz0weumE8s7paEk6g', // Roboco
    offset: 0,
    order: Order.descending,
    organization: Organization.Hololive,
    paginated: true,
    sort: <VideoSort>[VideoSort.availableAt],
    status: <VideoStatus>[VideoStatus.past],
    // Videos of type VideoType.clip cannot not have topic. Streams may or may not have topic.
    // topic: 'minecraft',
    type: VideoType.clip
);
print(videoList.toString());

Get a list of live videos

Returns VideoFullList

This is somewhat similar to calling listVideos().

However, this endpoint imposes these default values on the query parameters: You can choose to override them by providing your own values.

status: [VideoStatus.live, VideoStatus.upcoming],
type: VideoType.stream,
sort: [VideoSort.availableAt],
order: Order.ascending,
max_upcoming_hours: 48,
limit: 9999,
include: [Includes.liveInfo] + query's include

Arguments:

channelId Filter by video uploader channel ID
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang Filter by the Language
limit Limit the number of results returned.
maxUpcomingHours Number of maximum hours upcoming to get upcoming videos by (for rejecting waiting rooms that are two years out)
mentionedChannelId Filter by mentioned channel id, excludes itself. Generally used to find collabs/clips that include the requested channel
offset Receive results starting at this number in the array from the Holodex API
order Order by ascending or descending
organization Filter by clips that feature the org's talent or videos posted by the org's talent.
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.
sort Sort the returned data by this field
status Filter by the video status
topic Filter by video topic ID
type Filter by type of video, either clips or streams

final VideoFullList liveVideos = await holodexClient.getLiveVideos(
    includes: [
      Includes.channelStats
    ]
);
print(liveVideos.toString());

Get a channel by its ID

Returns Channel

Arguments:

channelId ID of the Youtube Channel that is being queried

final Channel ceresFauna = await holodexClient.getChannelFromId('UCO_aKKYxn4tvrqPjcTzZ6EQ');
print(ceresFauna.toString());

Get a list of channels

Arguments:

lang List of languages. Language is a property of Channel, so only Channels satisfying the language will be returned. Leave empty to search for Vtubers and/or all clippers.
limit Results limit
offset Offset results
order Order.ascending or Order.descending order, default ascending.
organization If set, filter for Vtubers belonging to a specific org
sort Column to sort on, leave default to use ChannelSort.organization as sort. Theoretically any value in ChannelSort should work

final List<Channel> channels = await holodexClient.getChannels(
    limit: 25,
    offset: 0,
    order: Order.ascending,
    organization: Organization.AtelierLive,
    sort: [ChannelSort.organization]
);
print(channels.toString());

Quickly Access Live / Upcoming for a set of Channels

This endpoint is similar to the getLiveVideos() method and usually replies much faster. It is more friendly in general. The cost to execute a lookup is significantly cheaper. It's unfortunately less customizable as a result.

We recommend using this if you have a fixed set of channel IDs to look up status for.

Arguments:

channelIds List of channel IDs to get the live videos from.

final List<Video> quickLiveVideos = await holodexClient.getLiveVideosFromChannelsQuickly([
    'UCQ0UDLQCjY0rmuxCDE38FGg', // Matsuri
    'UCZlDXzGoo7d44bwdNObFacg', // Kanata
    'UCqm3BQLlJfvkTsX_hvm0UmA' // Watame
]);
print('Requested Live Videos From Channels: ${quickLiveVideos.length}');

A simplified method for access channel specific data. If you want more customization, the same result can be obtained by calling the queryVideos() method.

Arguments

channelId ID of the Youtube Channel that is being queried
type The type of video resource to fetch. Clips finds clip videos of a vtuber channel, Video finds the channelId channel's uploads, and collabs finds videos uploaded by other channels that mention this channelId
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang List of Language enum to filter channels/clips. Official streams do not follow this parameter
limit Result limit. Max of 50.
offset Offset results
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.

final VideoFullList matsuriClips = await holodexClient.getVideosRelatedToChannel(
    'UCQ0UDLQCjY0rmuxCDE38FGg', // Matsuri
    type: VideoSearchType.clips
);
print('Clips including Matsuri: ${matsuriClips.total}');
print('Returned clips including Matsuri: ${matsuriClips.videos.length}');

Get Clips of a VTuber

Alias of getVideosRelatedToChannel()

Returns VideoFullList

Arguments

channelId ID of the Youtube Channel that is being queried
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang List of Language enum to filter channels/clips. Official streams do not follow this parameter
limit Result limit. Max of 50.
offset Offset results
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.

final VideoFullList matsuriClips = await holodexClient.getVTuberClips('UCQ0UDLQCjY0rmuxCDE38FGg');
print('Clips including Matsuri: ${matsuriClips.total}');
print('Returned clips including Matsuri: ${matsuriClips.videos.length}\n');

Get Collabs that mention a VTuber

Alias of getVideosRelatedToChannel()

Arguments

channelId ID of the Youtube Channel that is being queried
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang List of Language enum to filter channels/clips. Official streams do not follow this parameter
limit Result limit. Max of 50.
offset Offset results
paginated If paginated is set to any non-empty value, returns VideoFullList with total, otherwise returns VideoFullList without the total.

final VideoFullList matsuriCollabs = await holodexClient.getVTuberCollabs('UCQ0UDLQCjY0rmuxCDE38FGg');
print('Collabs including Matsuri: ${matsuriCollabs.total}');
print('Returned collabs including Matsuri: ${matsuriCollabs.videos.length}\n');

Get Videos From Channel

Alias of getVideosRelatedToChannel()

Returns VideoFullList

Arguments

channelId ID of the Youtube Channel that is being queried
includes Request extra data be included in the results. They are not guarenteed to be returned.
lang List of Language enum to filter channels/clips. Official streams do not follow this parameter
limit Result limit. Max of 50.
offset Offset results
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.

final VideoFullList matsuriUploads = await holodexClient.getChannelVideos('UCQ0UDLQCjY0rmuxCDE38FGg');
print('Total Matsuri uploads: ${matsuriUploads.total}');
print('Returned uploads: ${matsuriUploads.videos.length}\n');

Get a single Video's metadata

Retrieves Comments if timestampComments is set to true

Retrieves Recommendations if query parameter recommendationLanguages is set

final VideoMetadata videoMetadata = await holodexClient.getVideoMetadata(
    'eJJuy5rY57w', // Shion's singing stream
    timestampComments: true,
    recommendationLanguages: [Language.all],
);
final VideoFull shionSingingStream = videoMetadata.video;
final List<Comment>? timestampComments = videoMetadata.comments;
final List<Video>? recommendations = videoMetadata.recommendations;

print('Songs: ${shionSingingStream.songcount}');
print('Video Comments With Timestamps: ${timestampComments?.length}');
print('Video Recommendations: ${recommendations?.length}');

Search For Videos

Flexible endpoint to search for videos fufilling multiple conditions.

Descriptions with "any" implies an OR condition, and "all" implies a AND condition.

Searching for topics and clips is not supported, because clips do not contain topics

Arguments

searchSort Sort by newest or oldest
languages If set, will filter clips to only show clips with these languages + all vtuber streams (provided searchTargets is not set to filter out streams)
searchTargets Target types of videos
conditions Match all of the items. > For each item: Text to look for text in video title or description
topics Return videos that match one of the provided topics
vch Videos with all of the specified channel ids. If two or more channel IDs are specified, will only return their collabs, or if one channel is a clipper, it will only show clips of the other vtubers made by this clipper.
organizations Videos of channels in any of the specified organizations, or clips that involve a channel in the specified organization.
paginated If paginated is set to true, returns VideoFullList with total, otherwise returns VideoFullList without the total.
offset Offset results
limit Result limit

final VideoFullList searchVideos = await holodexClient.searchVideos(
    searchSort: SearchSort.newest,
    languages: [Language.all],
    searchTargets: [SearchTarget.clip, SearchTarget.stream],
    conditions: ['karaoke'],
    topics: ['singing'],
    vch: <String>[],
    organizations: [Organization.Hololive],
    paginated: true,
    offset: 0,
    limit: 25,
);
print('Videos Found: ${searchVideos.videos.length}\n');

Search For Videos With a Comment

Flexible endpoint to search for comments in videos fufilling multiple conditions.

Descriptions with "any" implies an OR condition, and "all" implies a AND condition.

Searching for topics and clips is not supported, because clips do not contain topics

Arguments

searchSort Sort by newest or oldest
languages If set, will filter clips to only show clips with these languages + all vtuber streams (provided searchTargets is not set to filter out streams)
searchTargets Target types of videos
comment Find videos with comments containing specified string (case insensitive)
topics Return videos that match one of the provided topics
vch Videos with all of the specified channel ids. If two or more channel IDs are specified, will only return their collabs, or if one channel is a clipper, it will only show clips of the other vtubers made by this clipper.
organizations Videos of channels in any of the specified organizations, or clips that involve a channel in the specified organization.
paginated If paginated is set to true, returns VideoWithCommentsList with total, otherwise returns VideoWithCommentsList without the total.
offset Offset results
limit Result limit

final VideoWithCommentsList searchComments = await holodexClient.searchComments(
    searchSort: SearchSort.newest,
    languages: [Language.all],
    searchTargets: [SearchTarget.clip, SearchTarget.stream],
    comment: 'shion',
    topics: ['singing'],
    vch: <String>[],
    organizations: [Organization.Hololive],
    paginated: true,
    offset: 0,
    limit: 25,
);
print('Videos with Comment: ${searchComments.videos.length}\n');

Additional information

Read the official API documentation here

Visit Holodex.net

Some of this package was based off of the C# version

Table of Contents

Features

Getting started

Usage

Get a video by its ID

Get a list of videos

Get a list of live videos

Get a channel by its ID

Get a list of channels

Quickly Access Live / Upcoming for a set of Channels

Get Clips of a VTuber

Get Collabs that mention a VTuber

Get Videos From Channel

Get a single Video's metadata

Search For Videos

Search For Videos With a Comment

Additional information

Libraries

dart_holodex_api package

Table of Contents

Features

Getting started

Usage

Get a video by its ID

Get a list of videos

Get a list of live videos

Get a channel by its ID

Get a list of channels

Quickly Access Live / Upcoming for a set of Channels

Get Videos Related To Channel

Get Clips of a VTuber

Get Collabs that mention a VTuber

Get Videos From Channel

Get a single Video's metadata

Search For Videos

Search For Videos With a Comment

Additional information

Libraries

dart_holodex_api package