This article is dedicated to Nudgis administrators who need to automate tasks using the Nudgis API, such as setting up a workflow subordinate to their information system.
Table of content
To make this function easier to use, UbiCast has created a Nudgis API client in Python with ready-to-use scripts. We will start by explaining the installation requirements for using these scripts. Then we'll go into detail about the use of certain relevant scripts in the context of the media lifecycle, statistics/metrics, and finally the reversibility process.
Before you start, you can access details of the Nudgis API via the ‘Administration > About this site > API documentation’ menu:
Prerequisites
To use the Nudgis API client, you need to install the Python environment.
Please consult the official Python project documentation for installation.
The Nudgis API client only requires the 'Requests' Python module to be installed as a dependency.
You will then need to download the source code for the Python implementation of the Nudgis API client
at this address: https://github.com/UbiCastTeam/mediaserver-client/releases/latest
Be sure to check regularly for updates to this code to ensure that the Nudgis API works properly
Then copy the example JSON configuration file ‘config.json.example’ into the examples directory under the name ‘config.json’ :
cd mediaserver-client-4.5
cp config.json.example examples/config.json
Finally, you need to edit the configuration file (config.json) by adding the API key of the API_KEY account that will run the script and the address of your Nudgis SERVER_URL server:
{
"API_KEY": "XXX",
"CLIENT_ID": "python-api-client",
"PROXIES": {
"http": "",
"https": ""
},
"SERVER_URL": "https://XXX",
"UPLOAD_CHUNK_SIZE": 5242880,
"VERIFY_SSL": false
}
You can find your API key on your Nudgis user profile page via My Profile > Display my API key :
To end this chapter, we strongly recommend that you create a dedicated API account without a password, and with only the permissions appropriate to the script being run. This account will not be able to connect to Nudgis (as the password is empty).
The site's master API key must never be used for the Nudgis API
Scripts usage
The available scripts can be found in the ‘examples’ directory of the project.
First of all, to check that the configuration in the ‘config.json’ file is correct and that you can communicate with your server, you need to run the ping_server.py script.
This script does not require any particular permission. The command must return a success, as well as the version number of your Nudgis server. A correct return will read as follows:
cd examples
python3 ping_server.py config.json
{'success': True, 'mediaserver': '13.0.1'}
Having successfully completed this test, you can now run the scripts in the examples directory. We'll begin our exploration by presenting scripts for managing your server's storage, saving disk space where possible.
Video life cycle
As your server's disk space is limited, you will need to clean up your videos regularly. This operation is made much easier by the scripts presented below. However, they should be used with the utmost care, as they will permanently delete data from your server. This is why these scripts allow you to carry out blank tests to validate the deletion conditions. To use them, you must have permission to access and delete the media in your catalogue.
The first script available is delete_video_qualities.py. It can be used to delete unwanted video qualities from a channel, or from a csv file. Once the script has been run, only the best quality of the MP4 (or MP3 if applicable) resource is retained. You must also have the ‘Resource files’ editing permission to be able to run this script.
But you can also choose which resolutions to delete individually. For example, to simulate deleting the 360p qualities of a channel (represented in the script by its identifier, or OID), run the following command:
python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360"
At the end of the script execution, the disk space that will be freed is displayed as follows:
Would have freed 1 GB (29 resources) if run with "--delete".
If the result is satisfactory, you can apply the deletion by adding the --delete option
python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360" --delete
The following command gives details of the script options:
python delete_video_qualities.py --help
The second script presented, cleanup_unwatched_media.py, deletes unviewed media. In addition to the media access and deletion permissions, this script requires the ‘Can see all statistics’ global permission and the ‘Resource files’ editing permission.
For example, the command to simulate the deletion of media that have 10 views (or less) for the year 2023 and put them in the recycle bin would be as follows:
python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash
You can specify a particular channel instead of addressing the whole catalog, if you add the --channel-oid option with the selected channel OID following :
python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob
At the end of the script execution, the disk space that will be freed is displayed as follows:
Trashing these VODs would have freed up to 61.4MB
If the result is satisfactory, you can apply the deletion by adding the --apply option:
python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob --apply
The following command gives details of the script options:
python cleanup_unwatched_media.py --help
To conclude this chapter, let's take a look at the mass_delete.py script, which allows you to perform a mass deletion by specifying a list of video identifiers with a CSV file in the first column. Lines beginning with ‘#’ are ignored.
The video ID can also be found in the permanent media link
This script requires the additional global ‘Can edit site settings’ permission and the ‘Resource files’ editing permission. Use the following command to run the script:
python mass_delete.py --conf config.json --csv ./videos-id.csv
The result should be similar to the following line:
Deleting these VODs would have freed 4.1 GB
If the result is satisfactory, you can apply the deletion by adding the --apply option:
python mass_delete.py --conf config.json --csv ./videos-id.csv --apply
If you don't want the media to go into the recycle bin, add the --permanent option. Be careful when using it, however, as deletion will be immediate and permanent:
python mass_delete.py --conf config.json --csv ./videos-id.csv --apply --permanent
The following command gives details of the script options:
python mass_delete.py --help
Statistics and metrics
A great deal of information about portal usage is available in the site interface, as described in the article 'Statistics in Nudgis'. However, you can go even further by using the csv_media_stats.py script, which can be used to extract metrics that are not available in the Nudgis statistics. For example, it is possible to obtain information on the distribution of your media by type, duration and data by contributor, such as the ten biggest contributors in terms of media posted, for example.
To be able to analyse this data, you first need to generate it by running the csv_media_generate.py script. You need to have the global ‘Can edit site settings’ permission to run this script, the command for which will generate a CSV file:
python csv_media_generate.py config.json
Once the file has been generated, you can run its analysis with the following command:
python csv_media_stats.py --input media-monserveur.fr.csv
It is also possible to retrieve the media list of a speaker in CSV format. Simply specify the speaker's email address using the --target-email option, using the list_media_for_speaker.py script. You must have permission to access and edit the media in the catalogue to use this script:
python list_media_for_speaker.py --conf config.json --target-email "test@ubicast.eu"
Reversibility
The Nudgis API also offers the option of recovering data for backup or migration. The backup_media.py script will generate a ZIP archive containing the video metadata and the best quality video asset. This script requires ‘Resources files’ and ‘Community settings’ editing permission. To save the media uploaded before 2024, use the following command:
python backup_media.py --conf config.json --date 2024-01-01
By default, the backup will go into the ‘backups’ directory
To delete the backed up files, add the --delete option. Be careful when using this option, however, as deletion will be immediate and definitive:
python backup_media.py --conf config.json --date 2024-01-01 --delete
The following command gives details of the script options:
python backup_media.py --help
The following script, backup_channel_recursive.py, allows you to restrict the backup by channel by specifying the channel identifier, but will also perform a default backup in the ‘backups’ directory:
python backup_channel_recursive.py --conf config.json --channel c12640c68e63b949rq65
To restore the backup on Nudgis, simply use the restore_media.py script and specify the directory of your backup. The media is restored in its original chain:
python restore_media.py --conf config.json --path backups
You can also restore media to another existing channel on your Nudgis server using the --channel option with the corresponding channel OID following. In this case, the media will be restored to that channel:
python restore_media.py --conf config.json --path backups --channel c1266553ef1690qfgln9
The last script, download_all_original_files.py, retrieves only the best quality of your original resource, which in most cases is the MP4 with the best resolution. To complete the command, simply specify a destination directory (‘VideosHD’ in the following example).
python download_all_original_files.py config.json VideosHD
We hope this article has helped you get to grips with this feature and its many possibilities. Don't hesitate to tell us about your experience of the Nudgis API in the comments!
Comments
0 comments
Please sign in to leave a comment.