Audio API Редактировано: 28.08.2020 в 04:15

Теперь в Easy VK есть Audio API. Неофициальное, да, но зато работает.
В реализации Audio API я постарался повторить все методы, которые существовали в прошлом API ВКонтакте на основе официальной документации, которое разработчики, к слову, закрыли. Так что можно сказать, что Audio API в Easy VK - это полностью экспериментальная фитча, которая не рекомендуется для использования, но и не противопоказана :D
В общем, все на Ваше усмотрение, может работать, а может и нет.

ЕСТЬ ВАЖНОЕ НО!
В Easy VK будут выходить периодически различные обновления, которые будут фиксить все ошибки Audio API. Я буду стараться поддерживать актуальные возможности раздела аудиозаписей ВКонтакте. Некоторые параметры просто напросто не поддерживаются в Audio API, но это только потому, что ВКонтакте сам их не поддерживает. Вот так вот. В общем, ниже я постарался описать все методы, и как с нимим работать.

# audio.get()

Метод получает список аудиозаписей из плейлиста, из группы, или из аудиозаписей пользователя.

Параметры

• owner_id - ID пользователя или группы, чьи аудиозаписис надо достать
• playlist_id - ID плейлиста, из которого надо взять аудозаписи
• offset - Смещение по аудиозаписям, вернет аудозаписи, начиная с номера offset

Метод, как и многие другие методы Audio API возвращает объект <Promise>, в resolve функцию возвращаются следующие объекты

	{
		json: Object, // Читайте описание в разделе JSON Audio Api 
		vkr: VKResponse, 
		vk: EasyVK
	}

http.audio.get({
	owner_id: -123675921
}).then(({vkr, json}) => {
	let offset;

	if (json.hasMore) {
		// Есть еще аудозаписи, делаем offset
		offset = json.nextOffset;
	}

	console.log(vkr);

});

# audio.getById()

Метод возвращает аудиозапись по заданному идентифекатору

Параметры

• ids - список идентифекаторов аудиозаписей

  
  	"2_67859194,-683495_39822725,2_63937759"
  

  Или массив строк

  
  	["2_67859194","-683495_39822725","2_63937759"]			
  

Метод вернет массив аудиозаписей AudioItem

http.audio.getById({
	ids: '-2000506793_456239022'
}).then(({vkr, json}) => {
		
	console.log(vkr[0])

})

# audio.search()

Очень-чень опасный метод, который я еще дорабатываю, но он уже вполне работает. Короче, этот метод ищет аудиозаписи

Параметры

• q - Строка поискового запроса, например "MORGENSHTERN"
• offset - Смещение по поисковой странице, API вернет аудиоизапись начиная с номера offset

К сожалению остальные параметры, вроде filter, пока что не работают

http.audio.search({
	q: "MORGENSHTERN"
}).then(({vkr}) => {
	
	console.log(vkr);

});

# audio.getLyrics()

Метод возвращает старые слова, текст к песне (то, что уже не работает на новых аудиозаписях, но актуально для старых)

Параметры

• lid - lyrics_id, можно взять из некоторых объектов аудиозаписей, которые можно получить с помощью методов audio.get() или audio.getById()

Примеров нет, так как в целом метод старый и не рекомендуется для использования

# audio.getCount()

Метод возвращает количество аудиозаписей пользователя или группы

Параметры

• owner_id - ID пользователя или группы, откуда нужно взять количество аудиозаписей

http.audio.getCount({
	owner_id: -123675921
}).then(({vkr}) => {
	console.log(vkr)
})

# audio.getUploadServer()

Метод возвращает URL для загрузки аудиозаписи

{
	// ответ
	upload_url: 'https://pu.vk.com/c815231/upload.php?act=load_audio&aid=0&gid=...'
}

Параметры

• gid
- ID группы, если есть необходимость загрузить в группу

http.audio.getUploadServer().then(({vkr}) => {
	console.log(vkr.upload_url);

	// Теперь можно загружать на url файл аудиозаписи
})

Как загружать, читайте ниже

# audio.upload()

Метод загружает на указанный URL адрес аудиозапись, точнее, просто файл, но его можно использовать, чтобы загрузить аудиозапись в профиль в связке с методом audio.getUploadServer(), чтобы получить URL для загрузки.

Параметры

• url * (<string>)

  URL адрес сервера, на который будет идти загрузка

• file_path * (<string>)

  Путь к файлу, который нужно загрузить

Метод вернет промежуточные данные для сохранения аудиозаписи, эти данные Вы можете использовать, чтобы сохранить аудиозапись в группу или у пользователя

let upload_url = 'https://pu.vk.com/c815231/upload.php?act=load_audio&aid=0&gid=...';
let mp3_path = __dirname + 'my.mp3';

http.audio.upload(upload_url, mp3_path).then(({vkr}) => {
	
	console.log(vkr);

})

Чтобы узнать, как сохранить файл, читайте документацию метода audio.save()

# audio.save()

Метод сохраняет аудиозапись после загрузки, в него надо передать только промежуточные данные, полученные с метода audio.upload()

Метод вернет сохраненную аудиозапись, объект AudioItem

http.audio.getUploadServer().then(({vkr}) => {
	let upload_url = vkr.upload_url;
	let mp3 = __dirname + 'my.mp3';

	http.audio.upload(upload_url, mp3).then(({vkr}) => {
			
		http.audio.save(vkr).then(({vkr: audio}) => {
			
			console.log(audio);

		})

	})
	

})

# audio.getURL()

Метод возвращает разобранный URL адрес mp3 файла аудиозаписи. Во многих местах mp3 аудиозаписи скрыт и, когда Вы попытаетесь прослушать аудиозапись из url, будет звучать что-то в роде "этому приложению не доступно прослушивание аудиозаписей ВКонтакте". Короче, нужно этот URL вставить в данный метод и он просто вернет разобранный нормальный URL по алгоритму

vk.call("wall.getById", {
	posts: "-149662823_108"
}).then(({vkr}) => {
	let post = vkr[0];
	
	let audio = post.attachments[1].audio;
	audio.url = http.audio.getURL(audio.url);

	console.log(audio);
	
})

# audio.add()

Метод добавляет выбранную аудиозапись в список аудиозаписей группы или пользователя

Аргументы

• audio * (<AudioItem>) - объект AudioItem, или просто объект такого типа

  
  {
  	owner_id: AUDIO_OWNER_ID,
  	id: AUDIO_ID,
  	add_hash: AUDIO_ADD_HASH
  }
  			

  Рекомендую брать данный объект из методов вроде audio.get() или audio.getById()

• params (<Object>) - список дополнительный настроек
  • group_id - id группы, в которую нужно добавить аудиозапись

http.audio.get({
	owner_id: -84720287
}).then(({vkr}) => {
	
	let audioObject = vkr[0];
	
	http.audio.add(audioObject).then(({vkr}) => {
			
		console.log(`Аудиозапись ${audioObject.title} добавлена!`);

	})

})

# audio.delete()

Метод удаляет аудиозапись

Принимает только один аргумент - объект аудиозаписи AudioItem

{
	id: AUDIO_ID,
	owner_id: AUDIO_OWNER_ID,
	delete_hash: AUDIO_DELETE_HASH	
}

Рекомендую брать данный объект из методов вроде audio.get() или audio.getById()

http.audio.get().then(({vkr}) => {
	
	let audioObject = vkr[0];

	http.audio.delete(audioObject).then(({vkr}) => {
			
		console.log(`Аудиозапись ${audioObject.title} удалена!`);

	});

});

# audio.edit()

Метод редактирует аудиозапись

Аргументы

• audio * (<AudioItem>) - объект аудиозаписи AudioItem или примерно такой объект

  
  {
  	owner_id: AUDIO_OWNER_ID,
  	edit_hash: AUDIO_EDIT_HASH,
  	id: AUDIO_ID
  }
  

  Рекомендую брать данный объект из методов вроде audio.get() или audio.getById()

• params - объект параметров запроса
  • title - новое название аудиозаписи (по умолчанию не изменяется)
  • privacy - аудиозапись скрыта из поиска

  
  {
  	privacy: [0, 1][0]
  }
  			

  • text - текст аудиозаписи, слова
  • performer - исполнитель трека
  • genre - номер жанра, можно взять из объекта AudioAPI

  
  AudioAPI.genres = {
  	1: "Rock",
  	2: "Pop",
  	3: "Rap & Hip-Hop",
  	4: "Easy Listening",
  	5: "Dance & House",
  	6: "Instrumental",
  	7: "Metal",
  	8: "Dubstep",
  	10: "Drum & Bass",
  	11: "Trance",
  	12: "Chanson",
  	13: "Ethnic",
  	14: "Acoustic & Vocal",
  	15: "Reggae",
  	16: "Classical",
  	17: "Indie Pop",
  	18: "Other",
  	19: "Speech",
  	21: "Alternative",
  	22: "Electropop & Disco",
  	1001: "Jazz & Blues",
  }
  				

  
  {
  	title: 'До зимы',
  	performer: 'Oxxxymiron',
  	genre: http.audio.genres[3]
  }
  				

Метод вернет отредактированную аудиозапись

http.audio.get().then(({vkr}) => {
	
	let audioObject = vkr[0];

	http.audio.edit(audioObject, {
		title: "Rest In Peace",
		performer: "Astrokai",
		genre: http.audio.genres[1001]
	}).then(({vkr}) => {
			
		console.log('Отредачили!', vkr);

	})

})

# audio.reorder()

Метод перемещает аудиозапись в списке аудиозаписей

Параметры

• audio_id - ID аудиозаписиси, которую нужно переместить
• after_audio_id - ID аудиозаписи, после которой в списке поместить выбранную аудиозапись. Аудиозапись переместится на место этой аудиозаписи

Пример, как я поменял 1ю аудиозапись местами со 2й

http.audio.get().then(({vkr}) => {
	
	let audios = vkr;
	
	http.audio.reorder({
		audio_id: audios[0].id,
		after_audio_id: audios[0].id
	}).then(({vkr}) => {
		
		console.log('Переместили!', vkr);

	});
	
});

# audio.restore()

Метод восстанавливает аудиозапись в списке аудиозаписей после удаления, точно не знаю через сколько времени уже нельзя восстановить аудиозапись

Аргументы

• audio * ( <AudioItem>) - объект аудиозаписи

  Рекомендую брать данный объект из методов вроде audio.get() или audio.getById()

http.audio.get().then(({vkr}) => {

	let audio = vkr[0];


	http.audio.delete(audio).then(() => {
		
		console.log('Удалили!');

		http.audio.restore(audio).then(() => {
			
			console.log('Восстановили!');

		})

	})
	
})

# audio.getPlaylists()

Метод возвращает список плейлистов пользователя или группы

Параметры

• owner_id - ID пользователя или группы, из которой надо достать список плейлистов
• offset - смещение по номеру плейлиста, начиная с этого номера будут возвращены новые плейлисты

Метод вернет массив плейлистов объекта Playlist, читайте документацию для этого объекта.

http.audio.getPlaylists({
	owner_id: -123675921
}).then(({vkr}) => {

	console.log(vkr[0].title);

});

# audio.getPlaylistById()

Метод возвращает плейлист по указанном параметрам

Параметры

• owner_id - ID владельца плейлиста (группа или пользователь)
• playlist_id - ID плейлиста, который нужно получить

Вернет объект плейлиста Playlist

http.audio.getPlaylistById({
	owner_id: -123675921,
	playlist_id: 1
}).then(({vkr}) => {
	
	console.log(vkr.title);

});

# audio.followPlaylist()

Метод добавляет плейлист в подписки (проще говоря, он добавляет чужой плейлист в список плейлистов пользователя, подписывается). Чтобы отписаться от плейлиста, надо вызвать метод повторно

Аргументы

• playlist * (<Playlist>) - объект плейлиста, или примерно такой бъект

  
  {
  	id: PLAYLIST_ID,
  	owner_id: PLAYLIST_OWNER_ID,
  	follow_hash: PLAYLIST_FOLLOW_HASH
  }
  		

  Рекомендую получать данный объект через методы вроде audio.getPlaylists() или audio.getPlaylistById()

http.audio.getPlaylists({
	owner_id: -123675921
}).then(({vkr}) => {
	
	let playlist = vkr[0];


	http.audio.followPlaylist(playlist).then(() => {
		
		console.log('Подписались!');

	})

})

# audio.deletePlaylist()

Метод удаляет плейлист из списка плейлистов (только СВОЙ плейлист, чужие нельзя удалить этим методом, всмысле, что, если Вы подписались на плейлист, надо отписаться, а не удалять его!)

Аргументы

• playlist * (<Playlist>) - объект плейлиста, или примерно такой бъект

  
  {
  	id: PLAYLIST_ID,
  	owner_id: PLAYLIST_OWNER_ID,
  	edit_hash: PLAYLIST_EDIT_HASH
  }
  		

  Рекомендую получать данный объект через методы вроде audio.getPlaylists() или audio.getPlaylistById()

http.audio.getPlaylists().then(({vkr}) => {
	
	let playlist = vkr[0];


	http.audio.deletePlaylist(playlist).then(() => {
		
		console.log('Удалили плейлист!');

	})

})

# audio.moveToPlaylist()

Метод добавляет аудиозапись в выбранный плейлист

Аргументы

• audio * (<AudioItem>) - Объект аудиозаписи

  Рекомендую брать данный объект из методов вроде audio.get() или audio.getById()

• playlist * (<Playlist>) - Объект плейлиста

  Рекомендую получать данный объект через методы вроде audio.getPlaylists() или audio.getPlaylistById()

http.audio.get().then(({vkr}) => {
	
	let audio = vkr[0];

	http.audio.getPlaylists().then(({vkr: playlists}) => {
		let playlist = playlists[0];

		http.audio.moveToPlaylist(audio, playlist).then(({vkr}) => {
			
			console.log('Добавили аудиозапись в плейлист!');

		})

	})

})

Playlist

Это объект плейлиста, который Easy VK генерирует автоматически при работе с плейлистами. В обобщенном виде он выглядет так:

{
	// ID плейлиста
	id: playlist.id,

	// ID владельца плейлиста
	owner_id: playlist.ownerId,

	// Полный идентифекатор плейлиста
	raw_id: playlist.ownerId + '_' + playlist.id,

	// Название плейлиста
	title: playlist.title,

	// Обложка плейлиста
	cover_url: playlist.coverUrl,

	// Дата последнего обновления
	last_updated: playlist.lastUpdated,

	// Содержит откровенный контент (мат)
	explicit: playlist.isExplicit,

	// Подписан ли пользователь на плейлист
	followed: playlist.isFollowed,

	// Подтвержденный плейлист (лицензия и т.п)
	official: playlist.isOfficial,

	// Сколько людей прослушали плейлист
	listens: playlist.listens,

	// Количество аудиозаписей в плейлисте
	size: playlist.size,
	
	// Все типы обложек
	covers: playlist.grid_covers,

	// Описание плейлиста
	description: playlist.description,

	// Маленькое описание плейлиста + HTML код
	raw_description: playlist.rawDescription,

	// Аудиозаписи плейлиста
	list: playlist.list
}

AudioItem

Это объект аудиозаписи, который Easy VK генерирует автоматически, когда работает с разделом аудиозаписей. Посмотрите, что он из себя представляет в обобщенном виде

AudioItem {
	id: 456239601,
	owner_id: 356607530,

	// URL адрес mp3 файла
	url:
	 'https://cs1-77v4.vkuseraudio.net/p13/d2f2dafd1d0e2d.mp3?extra=ZxfD...',
	
	// Название трека 
	title: 'Le clan des Siciliens',
	
	// Исполнитель
	performer: 'Ennio Morricone',
	
	// Продолжительность в секундах
	duration: 240, 

	// Список обложек
	covers:
	 'https://pp.userapi.com/c639520/v639520452/20464/qNd2FPHsB-0.jpg,https://pp
	.userapi.com/c639520/v639520452/20463/qXltktjrN1I.jpg',

	// Маленький размер обложки
	coverUrl_s: 
	 'https://pp.userapi.com/c639520/v639520452/20464/qNd2FPHsB-0.jpg',

	// Обложка размера постера
	coverUrl_p:
	 'https://pp.userapi.com/c639520/v639520452/20463/qXltktjrN1I.jpg', 

	// Флаги аудиозаписи (hq, и т.д)
	flags: 67,

	// высокое качество аудиозаписи (с недавних пор везде false)
	hq: false,
	
	// Подтверждено (типа по лицензии вроде)
	claimed: false,

	// Лицензия United Media Agency
	uma: false,

	// Взята из альбома
	album_id: 0,
	full_id: '356607530_456239601',

	// Содержит контент откровенного содержания (откровения тут это мат)
	explicit: false,

	// Не видел нигде, может старое что-то
	subtitle: '', 

	// Можно редактировать
	can_edit: true,

	// Можно удалить
	can_delete: true,

	// Можно добавить к себе
	can_add: true,

	// Cтарые данные аудиозаписи, тут же lyrics_id
	album: [ -2000050253, 50253, '41aa55652f111368ac' ],

	// ID слов песни, чтобы получить через audio.getLyrics()
	lyrics_id: 50253
}

JSON Audio Api

Данный объект возвращается в большинстве методов Audio API, и HTTP клиента. В нем хранится полный JSON ответ сервера ВКонтакте, его можно использовать для дебага, а также для того чтобы использовать полные возможности HTTP клиента. Так, например, в методе audio.get() в json возвращается объект с такимим параметрами, как hasMore, nextOffset и т.д

Данный объект сильно расширяет возможности клиента. Но помните один важный момент: точной документации для него не дать, Вы сами должны понимать, что в нем хранится, так как он всегда может придти разным (опять про нестабильность Audio API в целом, но это не минус, просто дотошность)

http.audio.get({
	owner_id: -123675921
}).then(({json}) => {
	console.log(json.hasMore) // Есть ли еще аудиозаписи
	console.log(json.nextOffset)
})