Это API позволяет управлять плейлистами вашей станции.

Пример: GET

Получить все плейлисты с сервера с ID 1:

import requests
API_KEY = "6aNLaqRN.87L4xZ5LUXwWLCkK7dBswDafWZNcaLOB"

headers = {"SC-API-KEY": API_KEY}

response = requests.get(
  "https://demo.streaming.center:1030/api/v2/playlists/?server=1",
  headers=headers
)
print(response.json())

Пример ответа

[
   {
      "id":1,
      "duration":9244067,
      "playlist_files_per_page":1000,
      "tracks_num":55,
      "name":"All music",
      "is_default":true,
      "is_random":true,
      "on_air":false,
      "directory_name":"",
      "current_track_order":-9,
      "server":1
   },
   {
      "id":2,
      "duration":9240712,
      "playlist_files_per_page":1000,
      "tracks_num":54,
      "name":"Morning shows",
      "is_default":false,
      "is_random":false,
      "on_air":true,
      "directory_name":"",
      "current_track_order":43,
      "server":1
   }
]

Описание

Этот API endpoint возвращает массив ваших плейлистов. Каждый плейлист содержит следующие свойства:

• id: уникальный ID плейлиста
• duration: длительность воспроизведения плейлиста в миллисекундах
• playlist_files_per_page: специальная настройка, ограничивающая количество треков плейлиста на одной странице. Влияет только на отображение плейлиста в административном веб-интерфейсе.
• tracks_num: количество треков в плейлисте
• name: название плейлиста
• is_default: boolean-значение, указывающее, является ли плейлист плейлистом по умолчанию на сервере. Вы не можете удалить плейлисты по умолчанию. Вся музыка, которую вы загружаете на сервер, добавляется в плейлист по умолчанию, который используется как запасной вариант, когда Auto DJ больше нечего воспроизводить. На сервере может быть только один плейлист по умолчанию. В нашем случае “All music” является плейлистом по умолчанию на сервере 1.
• is_random: указывает, перемешивается ли плейлист или воспроизводится последовательно по порядку.
• on_air: true, если плейлист воспроизводится в данный момент.
• directory_name: указывает, создан ли плейлист из директории сервера с включенной опцией синхронизации.
• current_track_order: число, указывающее текущую позицию воспроизведения в плейлисте.
• server: число, ID текущего сервера.

Пример: POST

Создать плейлист на сервере с ID 1:

import requests
API_KEY = "6aNLaqRN.87L4xZ5LUXwWLCkK7dBswDafWZNcaLOA"

headers = {"SC-API-KEY": API_KEY}

response = requests.post(
    "https://demo.streaming.center:1030/api/v2/playlists/", 
    headers=headers, 
    json={"name":"New playlist","is_random":True,"server":1}
)

if response.ok:
    print("The playlist was created successfully")
    newly_created_playlist = response.json()

Для создания плейлиста нужно отправить следующий JSON payload:

• name: название нового плейлиста
• is_random: передайте true, если хотите перемешивать плейлист
• server: целое число, обозначающее ID сервера.

Пример: POST-запрос для импорта файла плейлиста M3U.

Чтобы импортировать файл M3U, сначала необходимо загрузить сами аудиофайлы на сервер через FTP или веб-интерфейс. Затем отправьте POST-запрос с заголовком Content-Type, установленным в multipart/form-data. Вот как это сделать на Python:

import requests

API_KEY = "oaChhEn3.5Dnmm0rkJiJA4TNVE7266ypdOcp4Uakl"

headers = {"SC-API-KEY": API_KEY}

m3u_file = "import.m3u"
data = {
    "name":"m3u import",
    "is_random":True,
    "server":1
}
files = {
    'm3u': (m3u_file, open(m3u_file, 'rb'),)
}
response = requests.post(
    "https://demo.streaming.center:1030/api/v2/playlists/", 
    headers=headers, 
    data=data,
    files=files
)

Позволяет загрузить конкретный плейлист по ID при использовании метода GET и обновить плейлист при использовании метода PUT. С помощью метода DELETE можно удалить плейлист по ID.

Пример payload:

[40, 52, 7]

Этот endpoint позволяет добавлять треки в плейлист. Необходимо передать массив ID музыкальных файлов для треков, которые вы хотите добавить. Порядок ID в payload важен: треки будут добавлены в плейлист в том же порядке, в котором они указаны в массиве.

Позволяет запланировать воспроизведение плейлиста. Воспроизведение начнется в следующую полную минуту. Например, если вызвать это API в 11:30:25, в планировщике будет создано событие на 11:31 для запуска этого плейлиста. Этот endpoint не требует payload.

Создаёт копию плейлиста вместе с его треками.

Пример payload

{
    "new_name": "Morning shows copy"
}

Пример ответа

{
    "new_name": "Morning shows copy"
}

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

Пример payload

[101, 97, 105, 110]

Нужно передать массив ID записей из таблицы playlist tracks, а не ID треков из AllMusic. Endpoint возвращает пустой успешный ответ.

Перемешивает порядок всех треков в плейлисте. Endpoint не требует payload и возвращает пустой JSON-ответ.

Удаляет дубликаты одинаковых треков внутри одного плейлиста, оставляя по одному экземпляру. Endpoint не требует payload и возвращает пустой JSON-ответ.

Возвращает Excel-файл .xlsx со списком треков плейлиста. В таблицу включаются номер, имя файла, исполнитель, название, длительность и дата загрузки.

Добавляет в плейлист записи из директории recordings выбранного DJ. Файлы копируются в музыкальную библиотеку сервера и одновременно добавляются как новые записи AllMusic.

Пример payload

{
    "dj": 4,
    "recordings": ["show_2026_04_08.mp3", "guest_hour.mp3"]
}

Если recordings пустой, API вернёт ошибку 400.

Возвращает треки конкретного плейлиста с информацией о позиции и вложенным объектом трека из AllMusic.

Пример ответа

{
    "count": 2,
    "results": [
        {
            "id": 101,
            "order": 1,
            "flag": 0,
            "added_ts": "2026-04-08T09:10:11Z",
            "track": {
                "id": 40,
                "author": "Daft Punk",
                "title": "One More Time",
                "human_up": 12,
                "human_down": 1,
                "path": "/srv/media/Server_1/daft_punk_one_more_time.mp3"
            }
        }
    ]
}

GET возвращает один элемент плейлиста с вложенным треком. DELETE удаляет один или несколько элементов из плейлиста. Для массового удаления можно передать несколько ID через запятую в URL. После удаления API возвращает JSON вида:

{
    "length": 9231000
}

где length - обновлённая длительность плейлиста в миллисекундах.

Удаляет несколько элементов из плейлиста за один запрос.

Пример payload

{
    "tracks": [101, 102, 103],
    "fs": false
}

Поле tracks содержит ID записей playlist track. Если fs=true, связанные аудиофайлы также будут удалены из файловой системы. В ответе возвращается обновлённая длина плейлиста:

{
    "length": 9123000
}

Перемещает несколько элементов плейлиста на новую позицию.

Пример payload

{
    "tracks": [101, 102],
    "position": 5
}

position задаётся с единицы. При успехе endpoint возвращает пустой JSON-ответ.

API музыкальной базы AllMusic

Этот endpoint возвращает треки из музыкальной базы AllMusic.

Пример: GET

import requests

response = requests.get(
        "https://demo.streaming.center:1030/api/v2/music/?server=1&requestable=1&search_q=queen"
)
print(response.json())

Пример ответа

[
    {
        "id": 40,
        "server": 1,
        "author": "Queen",
        "title": "Radio Ga Ga",
        "album": "The Works",
        "genre": "Rock",
        "length": 343000,
        "path": "/srv/media/Server_1/queen_radio_ga_ga.mp3",
        "public_path": "/queen_radio_ga_ga.mp3",
        "filename": "queen_radio_ga_ga",
        "meta": "Queen - Radio Ga Ga",
        "requestable": true,
        "human_up": 25,
        "human_down": 2,
        "has_waveform": true,
        "length_formatted": "05:43",
        "category": {
            "id": 3,
            "name": "Rock"
        }
    }
]

Основные поля ответа AllMusic

• id: ID трека в музыкальной базе.
• server: ID радиосервера.
• path: полный путь к файлу или URL remote-файла.
• public_path: публичный относительный путь к файлу.
• filename: имя файла без расширения.
• meta: строка вида Author - Title.
• author: исполнитель.
• author_other: дополнительный исполнитель.
• title: название трека.
• album: альбом.
• genre: жанр.
• performance_type: вид исполнения.
• composer: композитор.
• lyricist: автор текста.
• publisher: издатель.
• label: лейбл.
• year: год.
• comment: комментарий.
• length: длительность в миллисекундах.
• length_formatted: форматированная длительность.
• samplerate: sample rate файла.
• audio_format: формат аудио.
• requestable: доступен ли трек для requests.
• requests_number: сколько раз трек заказывали.
• human_up: количество лайков.
• human_down: количество дизлайков.
• auto_up: рост слушателей на треке.
• auto_down: снижение слушателей на треке.
• tag_image: маленькая обложка.
• image_medium: средняя обложка.
• image_large: большая обложка.
• gain_db: сохранённая коррекция громкости.
• peak_value: peak-сигнал трека.
• isrc: ISRC-код.
• mbid: MusicBrainz ID.
• category: вложенный объект категории с полями id и name, либо null.
• playback_start_time: начало playback region.
• playback_end_time: конец playback region.
• playback_start_bytes_offset: смещение старта в байтах.
• playback_end_bytes_offset: смещение конца в байтах.
• playback_region_calculation_status: статус расчёта playback region.
• disable_crossfade: выключен ли crossfade для трека.
• has_waveform: есть ли сохранённая waveform.
• region_length: вычисленная длина playback region.
• max_volume_db: максимально допустимое увеличение уровня без перегруза.

GET возвращает один объект трека. PUT позволяет обновить метаданные, например author, title, album, genre, isrc, requestable, category и другие поля модели. DELETE удаляет трек из базы и удаляет соответствующий файл из storage.

Увеличивает счётчик лайков human_up у трека. Голосование ограничено одним голосом с одного IP за последние 24 часа.

Пример ответа

{
    "up": 26,
    "down": 2
}

Если этот IP уже голосовал, API вернёт 400 и ответ вида:

{
    "result": "already_voted",
    "up": 26,
    "down": 2
}

Работает аналогично like, но увеличивает счётчик human_down.

GET возвращает список ID плейлистов, в которые включён трек.

Пример ответа

{
    "playlists": [1, 2, 5]
}

POST синхронизирует принадлежность трека к плейлистам.

Пример payload

{
    "playlists": [1, 5, 6]
}

Пример ответа

{
    "added": [6],
    "removed": [2]
}

Возвращает массив уникальных значений поля author.

Возвращает массив уникальных значений поля genre.

Позволяет массово обновлять несколько треков AllMusic за один запрос.

Пример payload

{
    "update_mode": "overwrite",
    "track_ids": [40, 52, 70],
    "fields": {
        "genre": "Rock",
        "requestable": true
    }
}

Пример ответа

{
    "result": "ok",
    "updated": 3
}

update_mode может быть fill-empty или overwrite.

Этот endpoint отсутствует как collection route. Для переименования используется маршрут /api/v2/music/:id/rename/.

Переименовывает файл на файловой системе и обновляет путь в базе данных.

Пример payload

{
    "new_name": "queen_radio_ga_ga_remastered"
}

POST генерирует waveform для трека и сохраняет её в базе. GET возвращает бинарные данные waveform с content type application/octet-stream.

Обновляет playback region трека.

Пример payload

{
    "playback_start_time": 0.85,
    "playback_end_time": 176.12
}

После вызова поле playback_region_calculation_status переводится в состояние очереди на перерасчёт.

Возвращает дерево папок музыкальной библиотеки сервера.

Возвращает список файлов из выбранных папок музыкальной библиотеки.

Пример payload

{
    "folders": ["/Rock/", "/Gold/"],
    "text": "queen"
}

Дополнительно можно использовать query-параметр server.

Возвращает старый формат дерева музыкальной библиотеки с файлами и служебными полями tree, open и root.

Сбрасывает счётчики human_up и human_down у всех треков указанного сервера.

Пример payload

{
    "server_id": 1
}

Массово переключает флаг requestable у треков.

Пример payload

[
    {"id": 40, "requestable": true},
    {"id": 52, "requestable": false}
]

Возвращает только remote-треки, у которых path начинается с http или https.

Добавляет один remote-файл в AllMusic по URL после проверки доступности и аудиоформата.

Пример payload

{
    "server": 1,
    "path": "https://cdn.example.com/stream/track.mp3",
    "author": "Queen",
    "title": "Radio Ga Ga",
    "album": "The Works"
}

Позволяет быстро добавить несколько remote-файлов одним запросом.

Перемещает выбранные треки в другую директорию внутри музыкальной библиотеки сервера.

Пример payload

{
    "file_ids": [40, 52],
    "target_directory": "/Rock/Gold/",
    "server_id": 1
}

Пример ответа

{
    "moved_count": 2,
    "failed_count": 0,
    "moved_files": [
        {
            "id": 40,
            "old_path": "/srv/media/Server_1/track1.mp3",
            "new_path": "/srv/media/Server_1/Rock/Gold/track1.mp3",
            "filename": "track1.mp3"
        }
    ]
}

Удаляет выбранные файлы и, при необходимости, пустые директории.

Пример payload

{
    "server_id": 1,
    "files": [40, 52],
    "directories": ["Server_1/Rock/Old"],
    "ml": true
}

Если ml=true, соответствующие записи AllMusic тоже будут удалены из базы.

Загружает аудиофайл в указанную папку на сервере.

Параметры multipart/form-data

• filename: загружаемый файл.
• server_id: ID сервера.
• parent_dir: папка назначения.
• is_jingle: если true, файл загружается в директорию джинглов.

Как получить количество лайков у определённого трека по его ID из музыкальной базы AllMusic

Чтобы получить количество лайков у трека, выполните GET запрос к /api/v2/music/:id/, где :id — это ID объекта AllMusic. В ответе используйте поле human_up: именно оно содержит текущее число лайков трека.

Например, для трека с ID 40 запрос GET /api/v2/music/40/ вернёт объект трека, в котором поле human_up может выглядеть так:

{
    "id": 40,
    "author": "Queen",
    "title": "Radio Ga Ga",
    "human_up": 25,
    "human_down": 2
}

Если нужно не только прочитать текущее значение, но и сразу получить обновлённые счётчики после пользовательского голосования, можно вызвать POST /api/v2/music/:id/like/. В ответе API вернёт поля up и down, где up соответствует новому числу лайков.